这个Pages展示本项目的开发计划和项目文档

RK3588 NPU 驱动开发路线图

进度总览

当前状态：电源域管理 (Power Domain) 目标：将添加了npu驱动的starry编译拷贝到开发板验证探测

实际计划

第一阶段：环境验证与基础初始化

1. 理论与环境准备

• 阅读手册与 Demo
  • 研读 RK3588 技术参考手册中 NPU 章节。
  • 分析 RKNN Toolkit2 的官方 Demo，理解从模型加载到推理的完整数据流
• 实体机环境验证 (基于 StarryOS 比赛版)
  • 编译并烧录比赛版本的 StarryOS 代码到 RK3588 实体板。
  • 成功运行一个简单的文本生成模型，确保硬件和工具链正常。
• 整理 StarryOS 对 RK3588 NPU 驱动的逆向成果
  • 寄存器地图
    • 按模块梳理：PC / CORE / CNA / DPU / PPU / SDMA / DDMA / GLOBAL
    • 对每个寄存器记录：offset、字段含义、读写属性、默认值/复位值、关联流程
    • 标注来源：TRM / Linux rknpu 驱动
  • 提交协议与数据结构
    • 整理 DRM_IOCTL_RKNPU_* ioctl 列表与语义（Action / MemCreate / MemMap / MemDestroy / MemSync / Submit）
    • 对齐结构体布局：rknpu_mem_create / rknpu_mem_map / rknpu_task / rknpu_submit（字段意义与对齐）
    • 梳理 mmap(offset) 规则（handle 与 offset 的编码/解码约定）
  • 任务提交流程（时序 + 状态机）
    • 从“用户态提交”到“硬件执行完成”的完整时序
    • 失败路径：超时、异常中断状态、非法参数

第二阶段：异步推理支持

目标：将当前同步阻塞轮询的任务提交改为中断驱动的异步模式，提交任务后 CPU 不再空转等待，NPU 完成后通过中断通知。

实现情况

• 中断处理 — 实现 IRQ 驱动模式，CPU 通过 WFI 指令进入低功耗等待，NPU 完成后触发中断唤醒 CPU
• 异步等待机制 — 实现 wait_all_npucore 函数，支持多核心并行等待，每个核心独立触发中断
• 并发安全 — 每个核心维护独立的 irq_status 原子变量，避免多核并发访问冲突
• 超时与错误恢复 — 实现中断状态检查和错误传播机制，异常时正确上报错误码

第三阶段：NPU多任务并发运行

目标：支持多个NPU计算任务同时在NPU多核上进行

实现情况

• 硬件资源隔离 — 验证 3 个 NPU 核心的 PC/CORE/CNA 等寄存器 per-core 独立，GLOBAL 寄存器通过 core_idx 参数隔离
• GEM 内存隔离 — 实现 per-core 的 regcmd 缓冲区分配，每个核心使用独立的 DMA 地址空间
• 核心分配策略 — 实现 subcore_task 机制，支持灵活的核心分配，QKV 三核并行、Wo 单核等混合调度

项目日志

记录 RKNN NPU 驱动开发进展。

RKNPU技术报告

一、项目内容与用途

这个项目的对象是 RK3588 NPU 驱动及其在 StarryOS 上的系统集成。它的作用：让上层推理程序、benchmark 或后续 runtime 能稳定地把任务提交给 NPU 执行，而不是只能依赖 Linux 或闭源用户态库环境。

当前驱动已经覆盖了几条基础链路：

1. 寄存器/MMIO 访问：能够映射 RK3588 RKNPU 三个 core 的寄存器窗口，并通过寄存器接口完成 PC、CNA、DPU 等硬件模块的配置。
2. GEM/DMA 缓冲管理：支持用户态创建、映射、同步和销毁 NPU 可访问的 DMA buffer。
3. 任务描述符组织：支持 RknpuTask、regcmd、输入/权重/输出 buffer 的组合，并把这些描述符作为 submit 的基本执行单元。
4. ioctl 服务：支持 Submit、MemCreate、MemMap、MemDestroy、MemSync、Action 等 RKNPU 专用入口。
5. 中断与 completion 回收：IRQ handler 负责读取硬件完成状态，调度器再根据 core 绑定关系把 completion 还原到具体任务。
6. 多核调度：在一个 submit 中按 lane 把任务切到不同 core，同时支持多个 submit 进入队列等待。

二、本轮二次开发重点

2.1 支持 RK3588 三核 NPU 执行

RK3588 的 RKNPU 不是单个执行核心，而是三个可以并行工作的 NPU core。早期单核路径只证明了“任务能跑”，但没有把硬件并行能力发挥出来。本轮二次开发首先把提交路径改成能够识别 core_mask 和 subcore_task，让同一批任务可以被拆成多个 lane 分发到不同 core。

当前的三核执行模型可以概括为：

1. 用户态仍然通过一个 RknpuSubmit 提交任务批次。
2. subcore_task[] 描述每个 lane 的任务范围；如果用户态没有显式填写 lane，队列层会把任务归一化到默认 lane。
3. core_mask 决定这次 submit 允许使用哪些物理 core，例如 0x1 表示只用 core0，0x7 表示三个 core 都可用。
4. 调度器为每个空闲 core 挑选一个可派发 lane，然后调用底层 driver 对该 core 编程。
5. core 完成后，IRQ 路径发布 raw completion，调度器再回收并推进对应 lane 的 cursor。

这部分工作的重点不是简单把同一条命令发三遍，而是要保证每个 core 跑的是正确的 task slice，同一条 lane 不会被重复派发，completion 也能回到正确的 submit 和 task index。只有这些状态对齐，多核数据才有意义。

2.2 任务调度器与多线程共享 NPU

第二个是任务调度器。NPU 是共享硬件资源，不能让多个线程各自直接碰寄存器，否则很容易出现 core 状态、任务进度和 completion 归属混乱。当前实现保留外部的 blocking submit 语义，但内部引入了调度队列和 worker 线程：

1. 调用线程进入 Submit ioctl 后，不直接独占 NPU 跑完整批任务，而是把 submit 放进 scheduler。
2. 每个 submit 有自己的 waiter。调用线程只等待“自己的 submit 是否完成”。
3. 全局 worker 负责真正的 dispatch 和 harvest。它被 kick 唤醒后，先回收已完成 core，再给空闲 core 下发新任务。
4. scheduler 维护 ready、running、complete 这些状态。ready 表示还没开始跑的 submit，running 表示已有 lane 在跑或还有 lane 可继续派发，complete 表示终态结果等待 ioctl 路径取回。
5. 如果 running submit 还有可派发 lane，会优先继续推进 running，而不是马上切到一个全新的 ready submit。这样可以减少同一 submit 内部的等待空洞。

service 层的 blocking submit 通过 per-submit waiter 阻塞：调用线程在 wait_for_submit() 上等待，直到 worker 将该 submit 移入 complete 并调用 waiter.complete() 唤醒它，再通过 take_terminal_submit() 取回终态结果。多个用户线程同时提交 NPU 任务时，线程可以各自阻塞在自己的 waiter 上，NPU 由全局 worker 串行管理硬件状态并并行利用多个 core。换句话说，NPU 对外看起来仍是阻塞式设备，对内已经具备”多线程共享、队列化提交、三核流式执行”的基础形态。

这版调度器的价值就在这里：它没有把用户态 ABI 改复杂，但把内核侧的执行模型从"谁提交谁跑"推进到了"统一排队、统一分发、统一回收"。

2.3 引入 rknpu-regs 寄存器库

寄存器访问层也做了工程化整理，引入了基于 SVD / svd2rust 生成的 drivers/rknpu-regs。驱动开发里手写寄存器偏移和位域非常容易出错，尤其是 NPU 这种寄存器块多、字段分散、不同 core 地址重复的硬件。

rknpu-regs：

1. 用类型化寄存器接口替代裸地址和 magic number。
2. 减少手工抄写偏移、位宽、mask 时的错误。
3. 让寄存器访问代码更接近硬件文档，后续查错更方便。
4. 把”访问寄存器”和”调度策略”拆开，避免调度器里混入大量底层地址细节。

三、benchmark 测试内容

3.1 测量范围与方法

本次性能数据来自 log.txt 中运行的 ./core_scaling_benchmark，对应测试程序是 core_scaling_benchmark.c。

测量窗口：仅覆盖 blocking DRM_IOCTL_RKNPU_SUBMIT 的完整往返时间，即 submit ioctl 从进入到返回。operand packing 和 regcmd generation 单独打印，不计入对比窗口。因此下面的数据反映的是 driver submit、scheduler dispatch/harvest、硬件执行和 completion 回收的综合耗时

指标定义：

• speedup = T_1core / T_3core（同一批任务 1-core 与 3-core 的平均 submit 时间之比）
• parallel efficiency = speedup / 3（理想三核加速为 3x，efficiency 衡量实际利用率）
• GFLOP/s = 2 × GMAC/s（1 MAC = 1 乘 + 1 加 = 2 FLOP）
• jitter span = (T_max - T_min) / T_avg（衡量单次 submit 时间的波动幅度）

正确性校验：第一轮 measured round 会对输出抽样与 CPU reference 比较，并检查每个 task 的 int_status == 0x300。这是抽样校验，不是全量验证。

3.2 测试环境

• 硬件平台：RK3588 SoC（三核 NPU）
• 操作系统：StarryOS比赛版本
• Benchmark 程序：core_scaling_benchmark（4 场景 × 2 operand 模式）
• 测量轮次：每场景 warmup 2 轮 + measured 5-12 轮（场景相关）
• 频率/电源控制：未控制（默认 governor）
• 热稳态控制：未控制
• IRQ 亲和性：未设置

3.3 测试场景

每个场景一般又分两种 operand 模式：

1. shared-operands：所有任务复用同一份 input/weight，只有 output slice 私有。这更偏向测试调度和计算本身，DMA footprint 较小。
2. unique-operands：每个 task 有自己的 input/weight/output slice。这更接近多任务独立数据的情况，内存占用和准备成本更高。

测试程序里固定了四个场景。它们不是随便取的矩阵形状，而是分别压不同瓶颈：

tiny_dispatch 主要看调度器的“底噪”。如果这个场景三核退化，说明每次 dispatch、IRQ 回收、worker yield、waiter 唤醒的成本已经压过了硬件并行收益。它使用 96 个 task，任务数足够多，可以持续给三个 core 喂任务，但单 task 计算量非常小。

mid_balanced 是更接近日常 benchmark 的中间档。shared 模式有 48 个 task，unique 模式只有 12 个 task，因为 unique 模式每个 task 都有独立 input/weight/output，内存占用增长更快。这个场景用来观察调度器在“既有计算量、又有一定任务数量”的情况下是否稳定。

throughput_heavy 则故意把矩阵放大。shared 模式有 24 个 task，unique 模式只有 4 个 task。这里不是为了追求任务数，而是为了让每个 task 本身足够重，看三核并行能否把 GFLOP/s 拉上去。unique 任务数少也会暴露另一个问题：当任务批次太短时，三核并行窗口会变窄。

llama_decode_like 只跑 shared 模式，unique tasks 在测试程序里设为 0，所以日志里会跳过 unique。它模拟的是 decode 阶段常见的投影类 workload：M 很低，但 K 和 N 很大。这个场景不一定追求最高吞吐，更关心一次 submit 的阻塞时间能不能被多核明显压下来。

输入和权重不是随机数，而是由 deterministic_input_value() 和 deterministic_weight_value() 生成的整数模式；输出会抽样和 CPU reference 比较。每个 task 的 int_status 也会检查，期望值是 0x300。任务分发时，distribute_tasks_to_cores() 会按 core 数把 task range 平均切到 subcore_task[]，1 core 时只填 core0，3 cores 时填 core0/core1/core2 并设置对应 core_mask。因此这个 benchmark 测到的不是单纯的 C 程序循环，而是完整覆盖了 submit ABI、调度器 lane 切分、三核 dispatch、IRQ completion 和 copy-back 这些路径。

四、benchmark 结果与性能分析

4.1 总体结论

所有有效场景里，三核都比单核快，没有出现最终退化。最好的场景是 llama_decode_like/shared-operands，从 344.354 ms 降到 137.000 ms，speedup 达到 2.514x，parallel efficiency 为 83.78%。这说明调度器已经能把 RK3588 三个 NPU core 的并行能力用起来。

三核都有正收益,但大多数场景的 parallel efficiency 仍在 57% 到 68% 左右

4.2 结果汇总

4.3 tiny_dispatch：小任务也有明显收益

tiny_dispatch 的矩阵规模很小，单 task 的计算量低。当前结果里，shared 模式从 2.533 ms 降到 1.423 ms，unique 模式从 3.478 ms 降到 1.739 ms。这说明当前调度器的固定开销没有大到完全吞掉三核收益，小任务也能加速。

但是这个场景的性能不能过度解读。shared 模式 parallel efficiency 是 59.32%，unique 模式是 66.67%，距离理想三核加速2x以上仍有明显差距。小任务下，每次 dispatch 和 completion 的成本占比很高，真正花在矩阵计算上的时间太短。后续如果要优化小任务，需要减少每 task 的下发/回收成本，或者把更多小 task 合并成更粗粒度的 batch。

4.4 mid_balanced：中等任务证明调度器进入显著加速区间

mid_balanced 是这次比较有代表性的场景。shared 模式中，1 core 平均 submit 为 32.496 ms，3 core 为 18.746 ms，speedup 为 1.733x。unique 模式中，1 core 为 10.459 ms，3 core 为 6.065 ms，speedup 为 1.724x。

这个结果说明，调度器在中等任务规模下已经进入稳定可用区间。两种 operand 模式都接近 1.7x，没有只在某一种特殊数据复用方式下才有效。它也说明当前瓶颈不只是数据准备，因为 benchmark 的 measured window 没把 operand packing 算进去；submit 阶段本身确实因为多核并行缩短了。

4.5 throughput_heavy：吞吐型任务收益更明显

throughput_heavy 的 shared 模式从 42.656 ms 降到 20.864 ms，speedup 达到 2.044x，parallel efficiency 为 68.15%。同时 GFLOP/s 从 151.033 提升到 308.786，基本也是 2.044x 的增益。这个场景最能说明三核调度的直接价值：任务足够重之后，固定调度开销被摊薄，硬件并行执行开始成为主导因素。

unique 模式任务数只有 4 个，这是为了控制 DMA footprint。它仍然从 6.781 ms 降到 3.939 ms，speedup 为 1.721x。任务数少会限制三核利用率，因为 worker 能同时派发的 lane 数量和后续补发机会都变少。这个结果没有 shared 模式好，但仍然是稳定正收益。

4.6 llama_decode_like：长任务场景收益最好，但 jitter 较大

llama_decode_like 是本次最强的结果。它的 shared 模式从 344.354 ms 降到 137.000 ms，speedup 达到 2.514x，parallel efficiency 为 83.78%，GFLOP/s 从 4.677 提升到 11.756。这说明在低 M、高 K、高 N 的投影类 workload 下，当前三核调度能显著降低 submit 阻塞时间。

但这个场景也反应出在3-core 的 min/max 为 126.027 / 139.504 ms时，jitter span 达到 9.84%，明显高于 1-core 的 0.03%。也就是说，平均值很好，但三核路径下仍有一定波动。可能原因包括 worker harvest 时机、core completion 到达顺序、yield 后重新调度的时间差，以及更长任务下不同 core 之间的尾部等待。

4.7 这轮结果说明

1. 三核支持已经有效。所有有效 benchmark 场景都显示 3-core submit 时间低于 1-core。
2. 调度器设计已在真实 benchmark 中转化为性能收益。ready/running 队列推进、core binding 和 completion 回收这套机制能够有效利用三核并行。需要注意的是，当前 benchmark 验证的是单次 blocking submit 内的多核扩展收益，而非多线程并发提交的竞争场景——后者是调度器设计支持的能力，但尚未专项测试。
3. 软件开销仍然存在。大多数场景没有接近理想 3x，说明 dispatch、harvest、同步和调度唤醒成本仍然需要优化。

五、功能模块分层与实现思想

当前实现可以按从上到下的链路理解。

最上层是用户态 benchmark 或 runtime。它负责准备输入、权重、输出、regcmd 和 task array，然后通过 ioctl 提交任务。benchmark 还负责构造不同矩阵规模和不同 operand 共享模式，用来观察调度器在不同负载下的行为。

再往下是 ioctl / service 边界层。它负责把用户态传进来的 RknpuSubmit、RknpuTask[] 和内存管理请求拷入内核，转换成驱动内部可以处理的数据。这里不应该保存太多调度状态，否则 ioctl 层会变成第二个 scheduler。

scheduler 层负责 submit 生命周期。它维护 ready、running、complete 三个 bucket，管理每个 submit 的 waiter，也负责唤醒全局 worker。waiter 和 kick 的职责要分清：waiter 是 per-submit 的，回答"这个 submit 完成了吗"；kick 是全局 worker 信号，回答"现在有没有新活需要 worker 醒来处理"。这两个东西混在一起，调度器会很难读，也很容易漏唤醒。

driver / dispatch / IRQ 层负责硬件事实。driver 给某个 core 编程，IRQ handler 读取和清除硬件中断，completion 只表示"某个 core 有原始完成状态"。至于这个 completion 属于哪个 submit、哪个 lane、哪个 task index，应由 scheduler 根据 core_binding 还原，而不是让 driver 反向保存一堆队列语义。

最底层是寄存器访问层，也就是 rknpu-regs。它提供类型化 register API。调度器不应该知道太多寄存器细节，寄存器层也不应该知道队列策略。这个分层让后续工作可以分开推进：寄存器访问继续补全，调度策略继续优化，ioctl ABI 保持稳定。

六、当前限制与问题分析

1. 三核收益仍然低于理想值。除了 llama_decode_like 达到 83.78% efficiency，多数场景仍在 57% 到 68% 左右。说明当前并行并不是完全线性扩展，软件路径还有明显成本。
2. 小任务场景仍然敏感。tiny_dispatch 虽然这次有正收益，但它的绝对 submit 时间只有毫秒级，任何一次额外调度、yield、IRQ 回收或锁竞争都会改变结果。后续如果要跑大量小算子，必须继续压低固定开销。
3. 3-core 路径存在尾延迟波动。llama_decode_like 的平均 speedup 很好，但 3-core jitter span 到了 9.84%。这提示我们不能只盯 avg submit，还要看 min/max 和尾延迟。

七、调度器的执行时序

本节描述调度器的内部机制和执行流程，内容基于 drivers/rknpu/src/service/scheduler.rs 和 drivers/rknpu/src/task/taskqueen.rs 的实现。

7.1 核心数据结构

NpuSchedulerState（调度器全局状态，受单一 mutex 保护）：

• tasks: BTreeMap<RknpuQueueTaskId, RknpuQueueTask> — 所有活跃 submit 的唯一所有者
• ready: BTreeMap<i32, VecDeque<RknpuQueueTaskId>> — 按优先级分桶，尚未开始执行的 submit
• running: BTreeMap<i32, VecDeque<RknpuQueueTaskId>> — 按优先级分桶，已有 lane 在执行或还有 lane 可派发的 submit
• complete: BTreeMap<RknpuQueueTaskId, RknpuQueueTask> — 已终态，等待 ioctl 路径取回
• core_binding: BTreeMap<usize, CoreRunBinding> — 物理 core → {task_id, lane_slot, task_index} 的归属映射
• waiters: BTreeMap<RknpuQueueTaskId, Arc<W>> — per-submit 的阻塞等待器

RknpuQueueTask（单个 submit 的运行时状态）：

• lane_isrun: [bool; 5] — 每条 lane 是否有任务在飞
• subcore_cursors: [u32; 5] — 每条 lane 已完成的 task 数量
• last_error: Option<RknpuError> — 错误状态

submit 的生命周期状态（ready/running/complete）不是单独维护的枚举，而是由 lane_isrun、subcore_cursors、last_error 的组合派生，并通过 reclassify_task() 决定 submit 应归入哪个 bucket。

7.2 调度策略

running-before-ready：dispatch_idle_cores() 为每个空闲 core 选择候选时，优先从 running bucket 中找可继续派发的 submit（prepare_dispatch_from_running），只有当没有 running submit 可用时，才从 ready 提升新 submit（promote_ready_and_prepare_dispatch）。这减少了同一 submit 内部的等待空洞，但对等待中的 ready submit 不是严格公平的。

内存同步边界：

• comfirm_write_all()：在一次 dispatch_idle_cores() 调用中，对某个 submit 首次派发前调用，确保 DMA 写入对硬件可见
• prepare_read_all()：在 terminal submit 唤醒 waiter 前调用，确保硬件写回对 CPU 可见

7.3 图一：Submit 生命周期

注意:函数签名可能随着更新而改变实际函数签名以代码仓库中为准，此处只做流程解读

下图展示单个 submit 从 ioctl 入队到 copy-back 返回的完整路径，以及多个并发 submit 线程如何通过独立 waiter 共享同一个 worker。

7.4 图二：Worker 主循环与多核派发

注意:函数签名可能随着更新而改变实际函数签名以代码仓库中为准，此处只做流程解读

下图展示 worker 线程的主循环结构，以及 harvest 和 dispatch 如何交替推进多个 submit 的执行。

相关仓库

驱动主仓库

RKNPU

StarryOS与驱动的桥接层

rknpu-starry-adapter

演示视频

Video

PPT

PPT

第一周开发日志（1.25-1.31）

工作总结

• 基础知识学习 — 学习 NPU 原理、AI 模型运行原理、驱动在整个推理链条中的角色
• RKNN Toolkit2 仿真验证 — 下载套件，阅读 demo 代码，在 x86 仿真器上跑通测例

基础知识学习

刚接到 NPU 驱动开发任务时，虽然听说过 NPU，但对它实际是什么、解决什么问题、工作原理、如何运行都不了解。花了一天时间系统学习了以下内容：

• NPU 是什么 — 神经网络处理单元，专为矩阵运算和推理加速设计的硬件
• AI 模型的本质 — 本质上是一个函数，是大量矩阵乘法配上激活函数。训练是拟合参数，推理是执行前向传播
• 模型格式与转换 — ONNX → RKNN 格式转换，量化，以及模型在 NPU 上的执行流程
• 驱动在整个链条中的角色 — 用户态库（librknnrt.so）通过 ioctl 与内核驱动通信，驱动负责任务调度、DMA 搬运、寄存器操作

RKNN Toolkit2 套件与仿真验证

上 Rockchip 官网下载了 rknn-toolkit2 套件，发现里面包含一个 仿真器，可以在 x86 主机上模拟 RKNPU 的部分功能。阅读了 demo 代码，理解了 RKNN 推理的基本 API 调用流程：

rknn_init()来初始化npu执行上下文 → rknn_inputs_set()读写npu寄存器设置输出输出参数 → rknn_run()写npu寄存器提醒npu开始工作和运行 → rknn_outputs_get()npu通过中断通知操作系统，用户库从约定位置读取结果 → rknn_destroy()销毁释放npu执行上下文

第二周开发日志（2.1-2.7）

工作总结

• 开发板验证通过 — 在 OrangePi 5 Plus（RK3588）上部署 StarryOS（NPU 版本），成功跑通 RKNN 推理测例
• 闭源库逆向文档整理 — 整理了 librknnrt.so 逆向成果、完整寄存器语义、模型推理全链条，发布至 GitHub Pages
• 驱动骨架搭建 — 创建 axnpu-rknn 独立 crate，编写 DTB 设备探测代码，通过 rdrive 框架自动匹配 NPU 设备
• DRM 框架初步实现 — 创建 axdrm crate，实现 GEM 内存对象管理和 ioctl 编码解析与分发机制

开发板验证

搭载 RK3588 芯片的 OrangePi 5 Plus 开发板到了之后，将带有 NPU 支持的 StarryOS 版本（atomgit 仓库）部署到开发板上，成功跑通测例，验证了 NPU 驱动在 StarryOS 上的可行性。

闭源库逆向与文档整理

花了 3 天时间系统整理了以下内容：

• librknnrt.so 闭源库逆向成果 — 梳理了用户态库的内部调用流程、ioctl 命令、内存管理机制
• 寄存器语义 — 从官方 TRM 手册和 RKNN 开源内核驱动（C 语言版本）中，整理了完整的寄存器描述和语义
• 模型推理全链条 — 从 rknn_init 到 rknn_destroy 的完整生命周期，包括任务提交流程、状态机、DMA Fence 路径等

文档链接：https://qc-gpu-driver.github.io/starryos-pulsar/documents/docs.html

这份文档不仅方便自己开发时查阅，也相当于一份社区参考文档，我也会一直维护和验证的，方便更多对 RKNN NPU 驱动感兴趣的开发者查阅和使用。

驱动骨架编写

最初尝试直接在 arceos/modules/ 下创建 axnpu-rknn 驱动模块，但遇到了 workspace 循环依赖问题——ArceOS 的 axdriver_block 锁定的版本缺少 ahci feature，而 Cargo workspace 会全量解析所有 members 的依赖，导致整个 workspace 编译失败。

参考 StarryOS（NPU 版本）的做法，将驱动模块移动到 Starry 根目录下独立开发，等完善后再集成回 arceos。

编写了 dtbparse.rs，利用 ArceOS 的 rdrive 框架通过设备树（DTB）自动探测 NPU 设备：

#![allow(unused)]
fn main() {
module_driver! {
    name: "RKNPU",
    level: ProbeLevel::PostKernel,
    priority: ProbePriority::DEFAULT,
    probe_kinds: &[
        ProbeKind::Fdt {
            compatibles: &["rockchip,rk3588-rknn"],
            on_probe: probe_rknpu
        }
    ],
}

fn probe_rknpu(info: FdtInfo<'_>, dev: PlatformDevice) -> Result<(), OnProbeError> {
    let name = info.node.name();
    // 提取 MMIO 基址: 0xfdab0000, 大小: 0x9000
    let mut regs = info.node.reg().ok_or_else(|| { /* ... */ })?;
    let base_reg = regs.next().ok_or_else(|| { /* ... */ })?;
    let mmio_base = base_reg.address as usize;
    let mmio_size = base_reg.size.unwrap_or(0x9000);
    // 提取中断号: SPI 110, 111, 112（3 个 NPU 核心）
    // ...
    Ok(())
}
}

module_driver! 宏会将驱动自动注册到 rdrive 框架，内核启动时遍历 DTB，匹配 compatible = "rockchip,rk3588-rknn" 后自动调用 probe_rknpu，无需手动调用。

DRM 框架搭建

创建了 driver/axdrm crate，作为用户态接口适配层：

GEM 内存对象管理 — 实现了 GemNumberAllocator（handle 编号分配/回收）、GemObject（物理地址、虚拟地址、fake offset）、GemHandle（自动回收的 RAII handle）

ioctl 编码解析 — 实现了 DRM ioctl 命令的解码函数：

ioctl 分发机制 — 驱动通过 register_driver() 注册自己的 ioctl handler，dispatch_ioctl() 根据命令编号自动分发到对应驱动。NPU 驱动只需注册一个回调函数即可处理私有 ioctl。

第三周开发日志（2.8-2.14）

工作总结

• 修复 Axvisor 上 rsext4 文件系统导致的磁盘数据不一致问题 — 客户机写文件后重启出现 "block is free" 错误，定位为 rsext4 缓存未同步，在写操作后增加 sync_to_disk 调用修复
• svd2rust 寄存器库重构 — 基于 svd2rust 工具生成类型安全的寄存器访问库，重构 rknpu 驱动核心，减少手动操作寄存器的出错概率
• 辅助注释与文档 — 利用 AI 为驱动代码添加详细注释，兼顾学习与开发效率
• 基于 WFI 的异步中断处理 — 实现了 NPU 中断的异步等待机制

修复 Axvisor 上 rsext4 文件系统磁盘数据不一致问题

问题

1. 客户机执行文件写操作后重启，出现 block is free（双重释放，原来没有正确把1写回位图） （位图实际扫描使用的Block和超级块中的Block不一致）错误，磁盘数据损坏
2. 如果启动的是 Linux 客户机，Linux 在启动过程中会因文件系统完整性校验失败而无法启动

分析

Linux 客户机的问题是由于 Axvisor 在启动客户机的最后时刻调用 mount_virtual_fs 时没有刷新文件系统，导致文件系统不一致。Linux 启动时进行文件系统完整性校验，发现不一致后拒绝启动，随后关机导致缓存丢失，最终造成文件系统损坏。

根源在于 rsext4 为提升运行时性能设计了多级缓存机制，但 Axvisor 在集成 rsext4 时，没有在文件写操作后进行数据同步。如果客户机修改文件后立即关机，缓存仍停留在内存中，不可避免地导致磁盘数据不一致。

解决方案

在 rsext4 的 ext4fs.rs 访问层中，对所有写操作调用 sync_to_disk 函数，确保数据及时同步到磁盘。虽然会带来一定的性能损失，但保证了文件系统的一致性。

开发板环境踩坑

本周在板端遇到了一系列棘手的环境问题，花了不少时间排查：

U-Boot 与启动链问题

• U-Boot 缺少网卡驱动 — 板载 U-Boot 不支持网络传输，只能通过串口 loady 加载内核，debug 内核每次都要通过串口传内核很慢，每次修改都需要完整烧录StarryOS内核
• SPI 残留环境变量 — 从 OrangePi 官方 Ubuntu 镜像中提取干净的 U-Boot，制作 SPI 镜像刷入开发板。但刷完后发现 SPI 中残留了旧的 U-Boot 环境变量，导致启动失败，只能重新刷回 SPI 镜像
• eMMC 与 SD 卡混淆 — StarryOS 在开发板上扫描到板载 eMMC，但驱动却强制探测 SD 卡。起初误以为使用的是 SD 卡，经分析后确认实际使用的是板载 eMMC

后续 NPU 驱动工作开发路线决策

最初尝试将 NPU 驱动集成到 StarryOS 主线，但 HAL 层架构 axhal 与 somehal 存在冲突，RK3588 平台级代码集成涉及整个架构的大修改。为专注于 NPU 驱动核心功能开发，决定先在 StarryOS NPU 版本上开发，待主要功能完成后再移植回主线。

svd2rust 寄存器库重构

基于 svd2rust 工具重构 rknpu 驱动的寄存器访问层。

#![allow(unused)]
fn main() {
// 旧方式：手动偏移 + 裸指针
let status = unsafe { ptr.add(0x20).read_volatile() };
}

改进

通过 svd2rust 从 SVD 描述文件生成类型安全的寄存器库 rknpu-regs，每个寄存器字段都有明确的类型和文档：

#![allow(unused)]
fn main() {
// 新方式：类型安全 + 自动补全 + 文档
let status = core.pc().interrupt_status().read().bits();
core.pc().interrupt_clear().write(|w| unsafe { w.bits(INT_CLEAR_ALL) });
}

成果

• 生成了完整的寄存器定义，覆盖 PC、CNA、CORE、DPU、PPU、DDMA 等所有功能块
• RknpuCore 结构体封装了各功能块的访问方法，提供统一接口
• 编译期类型检查杜绝了寄存器偏移量写错、位域宽度搞混等常见错误

AI 辅助注释

利用 AI 为 axnpu 驱动代码添加了详细的中文注释(关键函数的调用流程和参数说明)

既方便自己学习 NPU 硬件细节，也降低了后续开发和他人协作的门槛。

基于 WFI 的异步中断处理

实现了 NPU 任务完成的异步等待机制：

• NPU 核心执行完任务后触发中断
• CPU 通过 WFI（Wait For Interrupt）指令进入低功耗等待状态
• 中断到来时 CPU 被唤醒，读取中断状态寄存器，清除中断标志
• 返回任务执行结果

这为后续多核并发任务提交打下了基础——每个 NPU 核心可以独立触发中断，CPU 侧可以并行等待多个核心的完成通知。

第五周开发日志（2.22-2.28）

工作总结

• RK3588 NPU 三核并行矩阵乘法实现 — 扩展 Transformer 结构体支持 3 套 regcmd 缓冲区，实现 matmul_npu_3core_qkv 函数，将 QKV 三个矩阵乘法并行提交到 3 个 NPU 核心，板端验证推理成功
• 驱动多核提交流程重构 — 修改 submit_ioctrl 实现批量任务分配，支持一次 ioctl 向多个核心提交任务，新增 wait_all_npucore 并行等待机制

验证结果

板端运行日志显示多核并行成功：

[261.640936] Total tasks to submit: 3, active cores: 3, max batch size: 4095
[261.650710] Total tasks to submit: 1, active cores: 1, max batch size: 4095
[262.295035] Total tasks to submit: 3, active cores: 3, max batch size: 4095
...
Once upon a time...

• 3 tasks, 3 cores 表示 QKV 三核并行成功
• 1 tasks, 1 core 表示后续的 wo 矩阵乘法（单核）
• 模型推理输出 "Once upon a time..." 验证结果正确

驱动多核提交流程重构

批量任务分配

重构 submit_ioctrl 函数，支持将用户空间的任务数组自动分配到多个 NPU 核心：

#![allow(unused)]
fn main() {
pub fn submit_ioctrl(&mut self, args: &mut RknpuSubmit) -> Result<(), RknpuError> {
    // 1. 刷新缓存，确保 NPU 能看到 CPU 写入的数据
    self.gem.comfirm_write_all()?;
    
    // 2. 提取活跃的核心任务
    let active_subcore: Vec<&RknpuSubcoreTask> = args.subcore_task.iter()
        .filter(|s| s.task_number > 0).collect();
    
    // 3. 批量提交到多个核心
    while task_iter < task_iter_end {
        let task_batch = active_subcore.len().min(task_iter_end - task_iter);
        let submit_tasks = unsafe { 
            core::slice::from_raw_parts_mut(task_ptr.add(task_iter), task_batch) 
        };
        
        // 并行启动每个核心的任务
        for idx in 0..active_subcore.len().min(task_batch) {
            self.base[idx].start_execute_one(idx, &self.data, &mut submit_tasks[idx], args)?;
        }
        
        // 并行等待所有核心完成
        self.wait_all_npucore(self.wait_fn, int_mask, submit_tasks)?;
        task_iter += task_batch;
    }
    
    // 4. 使缓存无效，确保 CPU 能读取 NPU 写入的结果
    self.gem.prepare_read_all()?;
    Ok(())
}
}

并行等待机制

新增 wait_all_npucore 函数，实现多核心并行等待：

#![allow(unused)]
fn main() {
pub fn wait_all_npucore(&self, normal_wait_fn: Option<fn()>, 
                        int_mask: Vec<u32>, 
                        submit_tasks: &mut [RknpuTask]) -> Result<(), RknpuError> {
    let mut done: [bool; 3] = [false; 3];
    
    if let Some(wait) = normal_wait_fn {
        // IRQ+WFI 模式：CPU 休眠等待中断
        loop {
            let status: Vec<u32> = self.base.iter()
                .map(|core| core.irq_status.load(Ordering::Acquire)).collect();
            
            // 检查每个核心的完成状态
            for idx in 0..submit_tasks.len() {
                if status[idx] & int_mask[idx] > 0 {
                    self.base[idx].clean_interrupts();
                    self.base[idx].irq_status.store(0, Ordering::Release);
                    submit_tasks[idx].int_status = int_mask[idx] & status[idx];
                    done[idx] = true;
                }
            }
            
            // 所有核心都完成则退出
            if done[..submit_tasks.len()].iter().filter(|&d| !d).count() == 0 {
                break;
            }
            
            // CPU 进入低功耗等待
            (wait)();
        }
    } else {
        panic!("[NPU] busy-poll mode not implemented for multi-core wait");
    }
    Ok(())
}
}

第六周开发日志（3.1-3.7）

工作总结

• NPU驱动移植到主线 — 将比赛版本上的 NPU 驱动和 aarch64 动态平台配置成功移植到 StarryOS 主线版本，系统启动成功，NPU 三核中断注册成功。不足：eMMC 驱动初始化失败导致系统崩溃，需要进一步排查；

• WFI 异步调度优化 — 将 WFI 函数替换为 yield 函数，实现真正的异步调度，NPU 工作时 CPU 可以执行其他任务，提升系统并发性能 不足：异步调度目前仅实现单核版本，SMP 完整实现仍在主线版本中

第七周开发日志（3.8-3.14）

• 工作进展：本周主要做的是规划，无实习任务相关的实质性代码工作

• 本周做出了对下周工作的详细规划以及个人对aarch64的详细学习

-规划如下:

NPU 协处理器化架构设计 (NPU as FPU)

1. 概述

本项目提出并实现一种创新的异构计算架构，旨在将 NPU 从传统的、基于 VFS/ioctl 的“设备”模型，提升为与 CPU 核心紧耦合的“协处理器”。其设计目标是通过极致的软硬件协同，实现 NPU 算力调度

2. 核心设计哲学

彻底废弃传统基于 VFS（虚拟文件系统）和 ioctl 的松耦合设备驱动模型。将 NPU 提升为与 CPU 平级的计算协处理器（类比 FPU 浮点运算单元）。通过共享 DMA 内存、定制化系统调用（Syscall）与“懒汉式”上下文切换（Lazy Context Switch）实现算力调度。

3. 内核数据结构扩展 (TCB 升级)

为了让操作系统的调度器（Scheduler）能够接管 NPU 资源，必须扩展内核的任务控制块（TCB / task_struct）：

• npu_isdirty: bool

  • 含义：NPU 硬件上下文“脏”标识位。
  • true：表示当前物理 NPU 硬件的内部 SRAM 和寄存器中，依然保留着该任务的数据和状态。
  • false：表示该任务的 NPU 状态已被换出，或者尚未使用过 NPU。

• npu_context: struct

  • 含义：NPU 硬件上下文结构体。追加在原生 CPU 任务上下文之后。
  • 作用：用于存储 NPU 被强行打断或切换时的完整硬件状态机。需查阅具体 NPU 芯片的闭源驱动源码及手册，提取并保存完整的寄存器集合（如命令队列指针、当前算子偏移量、中断屏蔽字等）。

4. 用户态基础框架 (libnpu)

在用户层封装底层细节，向应用程序开发者提供极简的 C/C++ 接口。

• 专属内存分配 (dma_malloc 系统调用)

  • 抛弃标准 malloc。用户通过 dma_malloc 直接向内核申请一段物理地址连续的 DMA 内存。
  • 目的：绕过 IOMMU 的复杂页表配置，让 NPU 硬件的 DMA 控制器可以直接通过物理地址（PA）高速拉取数据。

• 强制中断注入

  • 用户将计算参数、模型权重写入申请好的 DMA 内存区域。
  • 在构建 NPU 任务描述符（Task Descriptor）链表时，libnpu 会在底层介入，将每个微小可配置算子任务结构体中的中断控制位（IRQ Enable）强制设为开启。这是后续内核能够精准捕获算子边界、实现状态保存的关键。

• 内联汇编触发 (npu_work API)

  • 利用 AArch64 调用约定，将装载了任务描述符链表的 DMA 内存物理地址指针塞入约定的寄存器（如 X0）。
  • 执行定制的内联汇编（包含特定的 SVC 陷入指令），直接触发定制的 resolve_npu 系统调用。

5. 内核态调度核心 (resolve_npu 系统调用)

这是整个架构的调度心脏。当 CPU 通过 SVC 陷入内核态后，严格按照以下流水线执行：

阶段 1：内存转换与前置检查

1. 地址翻译：将 X0 寄存器传入的用户态虚拟地址（VA），通过查询页表或 DMA 分配记录，转换为 NPU 硬件所需的物理地址（PA）。
2. 硬件状态机检查：检查全局 NPU 硬件状态（IDLE 或 BUSY）。

阶段 2：懒汉式上下文切换 (Lazy Context Switch) 调度器需要仲裁当前物理 NPU 硬件的归属权。

1. 碰撞检测：检查系统中是否存在一个“前任任务”，其 npu_isdirty == true，且该任务并非当前请求任务。
2. 等待安全边界：如果存在这样的“前任任务”（说明 NPU 硬件中存有他人数据），内核绝不能强行复位硬件。必须检查 NPU 当前是否为 IDLE。如果是 BUSY，当前 CPU 线程必须挂起睡眠（加入等待队列），直到 NPU 算完当前算子并触发硬件中断。
3. 保存前任状态：当 NPU 确认处于 IDLE 后，内核立刻将 NPU 硬件内的全量寄存器状态抽取出来，保存到那个“前任任务”的 npu_context 中。
4. 剥夺前任所有权：将“前任任务”的 npu_isdirty 标志位修改为 false。

阶段 3：恢复当前状态并启动硬件

1. 检查当前记录：检查当前请求任务的 TCB 中，是否存有尚未跑完的 npu_context（即之前被切换出去的状态）。
2. 状态恢复：如果存在，则将 npu_context 里的数据原封不动地写回 NPU 的物理控制寄存器。
3. 宣誓主权：将当前任务的 npu_isdirty 标志位置为 true。
4. 硬件启动 (Kick the Doorbell)：将阶段1中转换好的任务描述符物理地址指针，写入 NPU 的“任务执行寄存器”，并写入特定的启动命令（“踢门铃”）。
5. 状态标记与返回：将全局 NPU 状态标记为 BUSY，CPU 退出系统调用，返回用户态继续执行或调度其他普通线程。

6. 硬件中断处理程序 (NPU IRQ Handler)

由于 libnpu 强制开启了每个算子的中断，NPU 每算完一个微小算子就会发出硬件 IRQ。

1. 进入 ISR：CPU 陷入内核中断服务例程。
2. 确认完成：读取 NPU 硬件状态寄存器，确认当前算子计算完成。
3. 释放路权：将全局 NPU 状态强制标记为 IDLE（空闲）。
4. 唤醒等待者：唤醒在 resolve_npu 系统调用中，因为 NPU BUSY 而挂起睡眠的其他任务线程，让它们得以重新参与 NPU 的抢占与上下文切换流程。

第八周开发日志（3.15-3.21）

工作总结

• 阶段性代码提交 — 本周完成一次阶段性代码提交 1d4e8fe，核心是把 rknpu 提交路径收敛为“单 task 边界步进 + 外层调度器轮转推进”，并补齐最小 DMA syscall 与用户态试验链路。提交链接：Commit
• NPU 提交路径支持单 task 边界切换 — 驱动只保留 submit_ioctrl_step_with_owner() 这条步进入口，在每个 task 完成 IRQ 边界返回，让多个进程可以轮流推进各自未完成的 submit
• DMA syscall 与用户态辅助库打通 — 保留 sys_dma_malloc、sys_dma_free 和对应轻量用户态封装，用于板端分配与释放 DMA 缓冲区
• 新增多进程/混合工作负载验证 — 新增 matmul_multi_process 与 matmul_llama_concurrent 两个测试程序，板端验证多进程交错提交和 llama 推理并发场景
• 寄存器级保存/恢复路径彻底下线 — 当前主线不再保留完整寄存器快照、恢复镜像、毒值写坏和读回校验逻辑，IRQ 路径只更新最小 owner/task 状态

单 task 边界调度改造

本周核心工作是把原来“一次 ioctl 一口气跑完整批任务”的同步提交逻辑，改造成“每次只推进一个当前 task-batch，完成后返回调度器”的步进式路径。

当前驱动只保留两类最小状态：

• NpuOwnerIds — 由外层调度器提供的 owner 标识，使用“线程 ID + 进程 ID + 地址空间指针”唯一标定一次 submit 的归属
• 每核 owner 槽位 — 每个硬件 core 只保留一个 NpuOwnerState，记录该 core 当前绑定的 owner、当前 task、task 指针、task 索引，以及最近一次 IRQ 的观测结果

不再保留：

• resident owner
• owner 级 submit/context 快照
• (owner, core) 共享状态表
• 完整寄存器保存/恢复镜像

新的路径大致如下：

1. card1 在进入 RKNPU_SUBMIT 时，用“当前线程 ID + 当前进程 ID + 当前地址空间指针”组装 owner
2. 驱动执行 submit_ioctrl_step_with_owner()，本次最多只推进一个 task-batch
3. 每个参与的 core 在下发前先绑定一个最小 NpuOwnerState
4. 每个核心收到预期完成中断后，驱动更新对应 task 的 int_status，同步回写 owner 槽位里的 IRQ 字段，然后立即清空该 core 槽位
5. 如果整次 submit 还没结束，就 yield_now() 主动让出，允许别的 owner 进来推进它自己的 submit
6. 下次同一个 owner 再进来时，只根据 task_counter 从上次稳定完成的位置继续

这样之后，进程级切换点就固定在了“单个 task 完成 IRQ 边界”上，而不是“整个 submit 全部完成”之后。

板端验证已经可以观察到这种交错推进：

[NPU]   batch done: int_status=0x300
...
matmul_multi_process: pass

这说明当前已经不是“一个进程一次性独占跑完整次 submit”，而是由外层 loop 在 task 边界轮流推进多个 owner。

多进程与混合负载测试

为了验证当前这套“单 task 边界切换”不是只在单个 demo 里自娱自乐，本周新增了两个更贴近真实使用方式的测试程序。

1. matmul_multi_process

这个测试会同时启动 4 个子进程。每个子进程只发起 1 次 submit，但这次 submit 里串了 20 个相关联的 matmul task：

• task 0 的输出作为 task 1 的输入
• task 1 的输出再作为 task 2 的输入
• …
• 最终做逐 task、逐元素 CPU 参考校验

它验证的不是“多个短任务抢一个锁”，而是：

• 单个 submit 内还有剩余 task 时，驱动能否在 IRQ 边界切出去
• 之后切回来时，能否从正确的 task_counter 继续推进
• 多个进程交错执行后，中间状态和最终输出是否仍然正确

最终板端结果为：

matmul_multi_process: pass

中断边界实验的收敛

本周原本也同步尝试了更激进的路线：在 IRQ 完成边界读取 live 寄存器快照，把准备恢复的寄存器先写入固定毒值，再按镜像恢复，最后读回校验。

但在板端验证时发现，至少有一部分 task-window 配置寄存器 在“任务刚完成、IRQ 已到达”的这个边界之后，并不保证还能按提交时的原值稳定读回。例如曾经观察到：

first_task_shadow_mismatch={ offset=0x100c, expected=0x120, got=0x0 }
first_task_shadow_mismatch={ offset=0x4058, expected=0xf, got=0x0 }

这说明两个事实：

• 当前边界对“task 已完成”是稳定的
• 但它不一定对“所有任务窗口寄存器还能按原值读回”稳定

因此当前版本做了一个更明确的收敛：

• 不再尝试保存/恢复整套寄存器镜像
• 不再保留毒值验证、恢复镜像、读回校验的主线逻辑
• IRQ 路径只保留“读取 live IRQ、清中断、更新最小 owner/task 槽位状态”

也就是说，当前主线解决的是“可运行、可验证、可继续扩展”的 task 粒度协作式调度基础设施；任意寄存器级/算子级抢占 不在本次提交范围内。

本周结论

本周最重要的进展，是把 单任务级边界（核 IRQ 中断边界）切换 + 多进程交错推进 + 结果正确 这一层跑通，并进一步把驱动内部状态压缩到了最小模型。

当前已经可以确认：

• 抢占/切换粒度已经从“整次 submit”下沉到了“单个 task 完成 IRQ 边界”
• 多个进程提交各自含有多 task 的 submit 时，驱动可以轮流推进
• 驱动内部不再承担 owner 上下文保存/恢复，也不再提供完整 NPU 状态导出接口

下一步的重点，是继续在当前 task 粒度调度稳定的基础上，围绕更细的调度与恢复能力评估真实可行的硬件边界，而不是继续维护一套过重的软件镜像模型。

第九周开发日志（3.22-3.29）

工作总结

本周的主要工作是实现一个基于 Clang front-end 的 RKNPU 代码生成工具。该工具面向“显式标注 + 代码生成”的使用模式：用户在 C 源码中对可加速代码段进行手工标注，工具负责识别被标注的算法结构，并将其转换为对应的 NPU 任务提交流程，从而把原本由 CPU 执行的计算卸载到 NPU 上。

当前版本已经完成从前端识别到代码生成的基础闭环，但支持范围仍较为有限，仅支持标准形态的 matmul 算子。 代码仓库

本周进展

• 完成了基于 Clang front-end 的前端识别方案，可以对带有显式标记的 C 代码进行分析。
• 完成了标准矩阵乘法代码模式的识别与验证，能够从纯 CPU 风格实现中提取出可下沉到 NPU 的计算区域。
• 实现了面向 RKNPU 的基础代码生成流程，能够将识别后的 matmul 区域转换为对应的 NPU 任务构造与提交流程。
• 建立了“手工标注 -> 识别分析 -> 代码生成”的最小闭环，为后续扩展更多算子和更复杂的调度机制打下基础。

遇到的问题与分析

本周原计划继续将 NPU 的任务调度粒度进一步细化到单个算子级别，以增加可调度时刻的数量，使单个进程占用 NPU 的最小时间片进一步缩小。

但在分析后发现，这一路径存在明显问题：如果将调度边界压缩到单个算子级别，将显著提高中断触发频率。虽然这样能够提升调度灵活性，但中断处理开销也会同步增大，整体性能收益并不理想，甚至可能得不偿失。

在此基础上，我进一步尝试思考和验证“任意时刻 checkpoint”方案，即在 NPU 运行过程中的任意时刻保存执行状态，并在之后恢复执行。当前主要遇到以下两个核心困难：

1. 硬件层面缺少统一暂停机制

   现有 RKNPU 硬件接口中，没有看到能够让多个功能部件在同一时刻一致性暂停的机制。因此，即使希望在某一时刻保存状态，也难以保证采集到的是一个全局一致、可恢复的硬件状态快照。

2. 恢复执行难以做到无副作用

   RKNPU 的启动方式本质上依赖于 PC 寄存器的启动脉冲。也就是说，恢复时并不是“从某个硬件内部断点继续执行”，而更接近一次重新触发执行。如果保存状态时任务正处于某个算子的执行过程中，那么恢复后很可能会导致该算子被重复执行，从而产生任务重放问题，破坏执行语义。

本周结论

本周完成了 RKNPU 代码生成工具链的第一版原型，实现了从 C 代码显式标注到 NPU 任务生成的基本流程，证明了“标准矩阵乘法代码经识别后自动生成 RKNPU 调用代码”这一方向是可行的。

第十周开发日志（3.30-4.5）

工作总结

本周的主要工作是完成 rknpu 任务调度器的正式落地。

这一周把提交、排队、分发、完成、唤醒这一整条路径实现了，让单次 submit 能在多核上并行推进，并在结束后正确返回到用户态。 提交链接

本周进展

• 完成了 rknpu 调度器主路径的搭建，路径为 card1 -> scheduler -> queue -> driver.
• 保留阻塞式 submit ，在内核内部为每次 submit 维护独立 waiter，使用户线程可以在提交后挂起等待，并在任务真正结束后被唤醒。
• 引入 worker 驱动的后台推进模型，通过全局 kick 机制唤醒调度线程，避免提交线程自己承担全部硬件推进逻辑。
• 完成多核分发路径，支持把同一批任务按 lane 切分后投递到多个 core 上并行执行。
• 把队列层的职责收敛到“维护 ready submit、lane 游标和完成进度”这几个核心状态上，调度器负责选择可下发任务，驱动负责实际硬件提交和中断观测。

本周结论

本周已经完成 rknpu 任务调度器的主体实现。当前版本具备了完整的阻塞提交、后台 worker 推进、多核 lane 分发、terminal 唤醒能力。

第十一周开发日志（4.6-4.12）

工作总结

本周的工作进入了收尾阶段，围绕已经完成的 rknpu 调度器做最后测试、benchmark 验证

本周进展

• 完成了多轮 benchmark 测试，覆盖 tiny_dispatch、mid_balanced、throughput_heavy 和 llama_decode_like 等场景，重点对比 1-core 与 3-core 的提交时间、吞吐和并行效率。
• 对调度器关键路径补充了更细的日志，覆盖 enqueue、worker 唤醒、dispatch、harvest、terminal wake 和 blocking wait 等节点。

遇到的问题与分析

本周最麻烦的问题，是 benchmark 过程中出现了偶发性的卡住或返回不稳定。

从现象上看，有些测试可以正常打印 benchmark complete status=0 并返回 shell；但也有一些运行过程中，会出现串口长时间停住、需要手动退出终端的情况。它并不是每次都能稳定复现。

结合当前benchmark日志，至少可以得到两个判断：

1. 小任务场景下，多核并行并不一定带来正收益

   在 tiny_dispatch 这类尺寸很小的 workload 上，submit/scheduler 开销占比很高，3-core 的效率明显达不到理想值，甚至可能比 1-core 更慢。这说明当前瓶颈更多在调度与提交流程，而不是硬件算力本身。

2. 中大型任务场景下，多核并行已经能稳定带来正收益

   结合这轮 benchmark 记录，可以直接看到几组比较明确的结果：

   • mid_balanced 场景下，1-core avg submit 从 56.158 ms 降到 39.204 ms，speedup = 1.432x，parallel efficiency = 47.75%
   • throughput_heavy 场景下，1-core avg submit 从 76.605 ms 降到 40.824 ms，speedup = 1.876x，parallel efficiency = 62.55%
   • llama_decode_like 场景下，1-core avg submit 从 423.358 ms 降到 231.858 ms，speedup = 1.826x，parallel efficiency = 60.86%

本周结论

本周完成了调度器收尾阶段最重要的一轮验证工作。当前版本已经能够支撑 benchmark 跑通，并能产出比较完整的日志和性能数据；

项目月报

2月技术报告-周雨

目标与问题

主要目标

1. 阅读 RKNPU 驱动相关源码，学习 NPU/AI 相关知识，将 RKNPU 硬件手册总结为 markdown 文档
2. 实现NPU驱动异步中断支持
3. 实现NPU驱动多核多任务并发

主要问题

1. 环境与工具链问题：开发板 U‑Boot 缺少网卡驱动，只能通过串口加载内核，调试效率低；U-boot网卡驱动编译困难，依赖太多，将会逐步解决
2. 驱动集成冲突：尝试将 NPU 驱动集成到 StarryOS 主线时，HAL 层架构 axhal 与 somehal 存在冲突，RK3588 平台级代码集成涉及整个架构的大修改。当前阶段将继续在当前已有驱动基础上开发。暂时不会集成到主线

方案或思路

面对上述问题，我制定了以下开发路线：

1. 分阶段学习与验证：

   • 第一阶段：学习 NPU 原理、AI 模型推理流程，利用 RKNN Toolkit2 仿真器在 x86 上验证推理链条。
   • 第二阶段：在真实硬件（OrangePi 5 Plus RK3588）上部署 StarryOS（NPU 版本），验证驱动可行性。
   • 第三阶段：逆向闭源用户态库 librknnrt.so，整理完整的寄存器语义和任务提交流程，形成社区参考文档。

2. 驱动架构设计：

   • 采用 rdrive 框架实现设备树（DTB）自动探测，避免硬编码设备地址。
   • 创建独立的 axdrm crate 实现 DRM 框架，提供 GEM 内存管理和 ioctl 编码解析/分发机制，保持用户态接口兼容性。
   • 将驱动模块放在 StarryOS 根目录独立开发，规避 workspace 循环依赖问题，待功能稳定后再集成回 ArceOS。

3. 寄存器访问安全：

   • 使用 svd2rust 工具从 SVD 描述文件生成类型安全的寄存器库 rknpu-regs，覆盖 PC、CNA、CORE、DPU、PPU、DDMA 等所有功能块。
   • 通过编译期类型检查杜绝寄存器偏移量写错、位域宽度混淆等错误。

4. 异步中断处理：

   • 利用 WFI（Wait For Interrupt）指令实现低功耗等待，NPU 核心完成任务后触发中断，CPU 被唤醒并读取中断状态寄存器。
   • 为后续多核并发任务提交奠定基础——每个 NPU 核心可独立触发中断，CPU 侧可并行等待多个核心的完成通知。

5. 多核并发任务调度：

   • 扩展驱动数据结构，支持多套寄存器命令缓冲区（regcmd）。
   • 重构 submit_ioctrl 函数，实现批量任务分配，一次 ioctl 可向多个核心提交任务。
   • 新增 wait_all_npucore 并行等待机制，循环检查各核心中断状态，直到所有核心完成任务。

6. 问题规避与迂回：

   • 暂时放弃将驱动集成到 StarryOS 主线，专注于在 NPU 版本上开发核心功能，减少架构冲突带来的干扰。
   • 通过刷写干净的 SPI 镜像解决 U‑Boot 环境变量残留问题，明确使用 eMMC 作为存储介质。

实现情况

1. 基础知识学习与仿真验证（第一周）

• NPU 原理学习：理解了 NPU 作为神经网络处理单元的本质，掌握了 AI 模型训练与推理的基本流程，以及驱动在推理链条中的角色（用户态库通过 ioctl 与内核驱动通信，驱动负责任务调度、DMA 搬运、寄存器操作）。
• RKNN Toolkit2 仿真验证：在 x86 主机上利用 RKNN Toolkit2 的仿真器跑通测例，梳理出 RKNN 推理的 API 调用流程：rknn_init → rknn_inputs_set → rknn_run → rknn_outputs_get → rknn_destroy。

2. 开发板验证与文档整理（第二周）

• 硬件验证：在 OrangePi 5 Plus（RK3588）开发板上成功部署 StarryOS（NPU 版本），并跑通 RKNN 推理测例，验证了 NPU 驱动在真实硬件上的可行性。
• 闭源库逆向与文档：系统逆向分析了 librknnrt.so 用户态库，结合官方 TRM 手册和开源内核驱动，整理了完整的寄存器语义、任务提交流程、状态机与 DMA Fence 路径，形成 GitHub Pages 文档，为社区提供参考。

3. 驱动骨架与 DRM 框架搭建（第二周）

• 设备探测：编写 dtbparse.rs，利用 rdrive 框架通过设备树（DTB）自动探测 NPU 设备（compatible = "rockchip,rk3588-rknn"），提取 MMIO 基址（0xfdab0000，大小 0x9000）和中断号（SPI 110‑112）。
• DRM 框架：创建 axdrm crate，实现 GEM 内存对象管理（handle 分配/回收、物理地址映射）和 ioctl 编码解析/分发机制，为 NPU 驱动提供兼容 Linux DRM 的用户态接口。

4. 寄存器库重构与 AI 辅助注释（第三周）

• svd2rust 寄存器库：基于 SVD 描述文件生成类型安全的寄存器库 rknpu-regs，覆盖 PC、CNA、CORE、DPU、PPU、DDMA 等所有功能块。将原有的手动偏移+裸指针访问改为类型安全、带自动补全和文档的 API，例如：

  #![allow(unused)]
  fn main() {
  let status = core.pc().interrupt_status().read().bits();
  core.pc().interrupt_clear().write(|w| unsafe { w.bits(INT_CLEAR_ALL) });
  }

• AI 辅助注释：利用 AI 为 axnpu 驱动代码添加详细的中文注释，明确关键函数的调用流程和参数含义，降低后续开发和协作门槛。

5. 异步中断处理实现（第三周）

• WFI 等待机制：实现基于 WFI（Wait For Interrupt）指令的低功耗异步等待。NPU 核心完成任务后触发中断，CPU 进入休眠状态；中断到来时 CPU 被唤醒，读取中断状态寄存器并清除标志位，返回任务执行结果。
• 多核中断基础：该机制为多核并发任务提交打下基础，每个 NPU 核心可独立触发中断，CPU 侧可并行等待多个核心的完成通知。

6. 多核并行矩阵乘法实现（第五周）

• 三核并行 QKV 计算：扩展 Transformer 结构体，支持 3 套 regcmd 缓冲区，实现 matmul_npu_3core_qkv 函数，将 Transformer 中的 Q、K、V 三个矩阵乘法并行提交到 3 个 NPU 核心。
• 批量任务分配：重构 submit_ioctrl 函数，支持将用户空间的任务数组自动分配到多个 NPU 核心，一次 ioctl 可向多个核心提交任务。
• 并行等待机制：新增 wait_all_npucore 函数，循环检查各核心中断状态，利用 WFI 等待所有核心完成，实现真正的多核并行等待。

7. 板端验证结果

板端运行日志显示多核并行成功：

[261.640936] Total tasks to submit: 3, active cores: 3, max batch size: 4095
[261.650710] Total tasks to submit: 1, active cores: 1, max batch size: 4095
[262.295035] Total tasks to submit: 3, active cores: 3, max batch size: 4095
...
Once upon a time...

• 3 tasks, 3 cores 表示 QKV 三核并行成功。
• 1 tasks, 1 core 表示后续的 wo 矩阵乘法（单核）。
• 模型推理输出 "Once upon a time..." 验证结果正确。

8. 其他问题修复（第三周）

• Axvisor 文件系统同步问题：修复了 rsext4 缓存未同步导致的磁盘数据不一致问题，在写操作后增加 sync_to_disk 调用，确保文件系统一致性（PR #368）。

下一步的计划/建议

基于 1 月末和 2 月份的开发进展，后续工作可围绕以下方向展开：

1. 驱动稳定性与健壮性

   • 当前驱动还有很多unimpliment函数和特性，我将会继续完善它
   • 完善错误处理机制，增强驱动健壮性

2. 多核调度优化

   • 实现动态负载均衡，根据各 NPU 核心的利用率自动分配任务。（当前多核并发是简单的任务切片）
   • 支持任务优先级调度，确保高优先级任务优先执行。
   • 探索任务依赖关系（DAG）支持，实现复杂模型层的流水线并行。

3. 主线集成与代码重构

   • 待 NPU 驱动功能稳定后，重新评估集成到 StarryOS 主线的可行性，解决 HAL 层冲突。
   • 将 axnpu-rknn 驱动模块迁移回 ArceOS 的 modules/ 目录，遵循项目模块化规范。

4. 文档与社区建设

   • 持续更新 GitHub Pages 文档，补充更多寄存器细节、性能调优指南和故障排查案例。

3月技术报告-周雨

目标与问题

主要目标

1. 将比赛版本中的 NPU 驱动和 aarch64 动态平台配置迁回 StarryOS 主线，先验证主线环境能不能真正承载 RKNPU 驱动，而不是一直停留在比赛分支上单独维护。
2. 将原来一次性跑完整个 submit 的同步提交路径，改造成在 task 完成边界主动让出的协作式调度路径，让多个进程在共享 NPU 时有明确的切换点。
3. 在驱动工作逐步稳定之后，继续往上层工具链推进，探索从带标注的 C 代码自动生成 RKNPU 调用代码，减少手工拼装任务描述符和提交流程的工作量。

主要问题

1. 主线移植后虽然系统能够启动，NPU 三核中断也能注册成功，但目前平台适配层还有一些问题，实际调用 NPU 时会出现卡死。这个问题我还在继续排查，也说明主线环境离稳定开发还有一段距离。
2. 更细粒度的调度与状态恢复并不只是软件设计问题。我在实验过程中已经明显碰到 RKNPU 的硬件边界。基于目前已经能稳定工作的单 task 粒度，我也认为没有必要继续追求任意时刻的调度，这件事现在看起来性能收益和工程收益都不大。
3. 自动代码生成工具虽然已经跑通了 matmul 的最小闭环，但目前识别和生成能力都还非常有限

方案或思路

面对这些问题，我在 3 月的思路比 2 月更聚焦一些。2 月更多是在补驱动能力，3 月开始，我更在意这些能力能不能放回主线、能不能被调度，以及在确认硬件边界之后，哪些事情值得继续做，哪些事情应该及时收口。

1. 将NPU驱动从比赛版本移植回主线

   我是先把比赛版本上的 NPU 驱动和平台适配层移植回了主线，然后在实际使用NPU驱动时会导致系统卡死，目前问题正在排查中

2. 从单线程任务独占改为多线程task step 协作式调度

   3 月中期我花了一段时间重新想调度模型。当时我甚至考虑过把 NPU 做成类似 FPU 的协处理器，同时尽量把 ioctl 路径收得很薄。我往下做时，我是先把最重要的部分抽出来：不要再让一个 submit 一次性独占 NPU 到结束，而是把提交拆成 step，每次只推进一个当前 task-batch，在 IRQ 边界返回，由外层调度器决定谁继续。后面的工作重点也不是把切换做得越来越激进，而是继续把驱动层这套 task step 调度机制做扎实、做到能稳定的跑为止。

3. 先用实验确认硬件边界，再主动收敛模型

   我不想在还没确认硬件边界的时候，就先堆一套很重的软件上下文模型。所以 3 月里我专门对寄存器快照、恢复镜像、算子级中断和 checkpoint（也就是执行中途保存状态，之后再恢复继续跑）做了实验。实验结果如果不支持，我就直接暂时搁置这条路，而不是继续维护一套看起来完整、实际上很难跑通的设计，而且实验看来在如果要做到任意时刻打断和恢复的话必定需要NPU硬件本身支持checkpoint的一种恢复机制。现在看下来，在单 task 粒度已经能稳定切换的前提下，没有必要再把目标扩展到任意时刻调度，继续往那个方向做，开销会更高，收益却不明显。

4. 向工具链上移，减少手工写驱动调用

   到 3 月后半段，我开始把目光往上移，不再只盯着驱动内部。具体做法是基于 Clang front-end，也就是利用 Clang 编译器前端的语法分析能力，对带有显式标注的 C 代码做识别，然后尝试自动生成对应的 RKNPU 调用代码。第一步只做标准 matmul，先把最小闭环跑通。

实现情况

1. NPU驱动移植回 StarryOS 主线并完成基础验证

3 月一开始，我做的不是新功能，而是把比赛版本上的 NPU 驱动和 aarch64 动态平台配置迁回 StarryOS 主线。

实际验证结果比我预想得好一些。系统能够正常启动，NPU 三核中断注册也成功了。

问题：目前平台适配层还有一些问题，实际调用 NPU 时会出现卡死，具体原因我还在继续排查。

2. npu驱动中任务提交路径改造成单 task 边界协作式调度

这一部分是我 3 月最核心的工作。之前的模型很直接：一次 ioctl 进去，驱动把单个线程提交的整个 submit 从头跑到尾，跑完才返回。这样做实现起来不难，但问题也很明显，单个线程会长时间独占 NPU。只要 submit 足够长，别的线程就只能一直等。

我后来把这条路径改成了单步推进。具体做法是，在 card1 的提交路径里保留外层 loop + yield_now()，而驱动内部只保留 submit_ioctrl_step_with_owner() 这个 step 入口。这个函数每次最多只推进一个当前 task-batch，然后就在 task 完成后的 IRQ 边界返回。为了让它能重新进入，我把 task_counter 作为唯一恢复游标，下次进入时直接从上次稳定完成的位置继续算，不再另外维护一套复杂的快照。

驱动内部的状态也一起收窄了。每次 step 下发前，只给参与执行的 core 绑定一个最小的 owner/task 状态，用来记录“这个 core 当前在给谁跑哪个 task，以及最近看到了什么 IRQ”。任务完成后，驱动更新对应 task 的 int_status 和最近一次 IRQ 观测值，然后立刻把 core 槽位清掉。这样做的好处：切换点清楚，状态模型也足够小。

板端验证能说明这条路是通的。多进程 matmul_multi_process 和混合负载场景已经跑通，submit 不再是一家独占跑完，而是多个 owner 在 task 边界交错推进。这里的切换本质上还是协作式调度，不是任意时刻抢占。它解决的是多个线程怎么共享 NPU，不是怎么把 NPU 做成一个可以像 CPU/FPU 那样随时保存和恢复的通用协处理器。

3. NPU驱动更细粒度调度与状态恢复实验带来的收敛

我一开始其实想得更激进。我不满足于 task 边界调度，还想继续往下压，看看能不能做到更细粒度的切换，甚至尝试类似 checkpoint 的执行中途保存与恢复。为此，我在 IRQ 边界做过 live 寄存器快照、毒值写坏和恢复校验，也专门分析过算子级调度的可能性。

板端实验给出的反馈并不乐观。我当时观察到过这样的日志：

first_task_shadow_mismatch={ offset=0x100c, expected=0x120, got=0x0 }
first_task_shadow_mismatch={ offset=0x4058, expected=0xf, got=0x0 }

这说明一个很麻烦的问题：IRQ 虽然已经到了，task 也确实跑完了，但并不是所有 task-window 配置寄存器都会在这个边界上稳定地按提交值读回。也就是说，这个边界对“任务完成”是可靠的，对“完整寄存器状态可恢复”却不是。再往下走，如果把调度边界压到单个算子，中断频率会明显变高，灵活性是提高了，但中断和调度开销也会一起涨上来。更关键的是，当前硬件接口里我没有看到一个能让多个功能部件在同一时刻一致性暂停的机制，而恢复执行也不像 CPU/FPU 那样能从内部断点继续，更像重新触发一次执行，这就带来了任务重放的风险。

这些实验让我最后收敛得很明确：当前最稳妥的边界，仍然是 task 完成后的 IRQ 边界。所以 3 月我做出的判断不是完整寄存器保存/恢复写不下去，而是这条路在当前硬件边界下不值得继续当主线推进。再往任意时刻调度上做，软件会更复杂，中断和调度开销也会更高，但我现在看不到足够明显的收益。这也是为什么后来我把主线彻底收敛到了task 粒度协作式调度，并开始把精力放回驱动层任务调度本身的完善和优化。

4. 基于 Clang front-end 的 RKNPU 代码生成工具原型

3 月后半段，我开始结合ai工具做一个基于 Clang front-end 的 RKNPU 代码生成工具。这里的想法很直接：写纯cpu计算的代码，通过手工标注一段代码，让代码生成工具来进行中间的具体的NPU平台侧的代码生成和优化，这样我们我们不用写一行npu库相关的代码 而是让我们的代码生成工具来分析代码生成更优，性能更好的能跑在npu上的代码，这也是当时我想的最贴近让npu当作cpu的一个协处理器在软件层面的一个思路.

当前的做法是“显式标注 + 前端识别 + 代码生成”。用户先在 C 代码里标出可加速的区域，工具再利用 Clang front-end 对这些区域做语法级分析。目前我已经把标准形态的 matmul 识别跑通，并且能够把识别出的计算区域转换成对应的 RKNPU 任务构造与提交流程，形成一个最小闭环。代码仓库见 rknpu_gen。

当然，这一步离“通用自动生成”还差得很远。现在它能说明的，只是标准 matmul 这条链可以走通，不能说明复杂算子、复杂控制流或者更随意的代码风格也都能自动处理。但这一步还是很重要，因为它把我 3 月的工作从“让驱动能跑”往前推到了“让工具帮人用驱动”。这两个方向其实不是一回事。

下一步的计划/建议

1. 继续排查和修复 StarryOS 主线下的平台适配问题，重点把当前“调用 NPU 会卡死”的原因定位清楚，让主线环境真正适合稳定调试。
2. 在现有 task 边界协作式调度已经稳定的前提下，继续完善驱动层的任务调度和优化工作，把队列化、优先级和多任务推进模型做得更规范。
3. 继续把多进程和混合工作负载测试做得更系统，确认当前 task step 调度在不同负载下的行为和开销，不再把任意时刻寄存器恢复作为当前主线目标。
4. 最后做一个benchmark来验证我优化前后驱动性能的提升

4月技术报告-周雨

目标与问题

主要目标

1. rknpu 任务调度器的正式落地：可以基于优先级调度处理多个线程提交的 submit。
2. 驱动的工程化重构：将 RKNPU 驱动抽象为一个独立且通用的 Rust crates 库，外部 OS 通过实现驱动所需的 trait 来使用驱动，实现内核与驱动逻辑的解耦。
3. 调度器性能验证：对完成的调度器进行全面的 Benchmark 验证，重点对比多核（3-core）与单核（1-core）在不同尺度 workload 下的提交时间与并行效率，产出完整的性能数据。

具体方案

1. 搭建后台 Worker 推进模型，解耦用户提交与调度器

为了避免用户线程长时间阻塞并承担硬件推进逻辑，我重新设计了提交流程：

• 后台 Worker 线程：设计了专门用于任务调度的 worker 线程。该线程在后台循环推进和调度任务。当没有任务时，worker 线程会进入两阶段睡眠（基于 listen 和 wait），挂起在监听新任务的信号量上；当有新任务入队时，通过全局的 notify_one (kick) 机制去唤醒调度线程。
• 用户态阻塞与唤醒：用户线程只需要调用 ioctl 接口将 NPU 任务入队即可睡眠等待。为此，我为每次 submit 维护了独立的 waiter（基于 RknpuSubmitWaiter trait）。用户线程在提交任务后直接挂起 (wait)，直到任务在多核上真正结束并触发 terminal，再由底层调用 complete 唤醒用户线程，安全返回用户态。

2. 将 RKNPU 驱动抽象为通用 Crate

为了让 RKNPU 驱动不依赖于特定的 OS 环境（如 StarryOS），我在 crate 层设计了一套平台相关的 Trait 接口，外部 OS 只需要实现 RknpuPlatform 即可接入驱动。具体拆分如下：

• RknpuDeviceAccess：负责底层设备的临时可变借用（with_device），由 OS 决定低层级 RKNPU 实例的存储和锁机制。
• RknpuUserMemory：抽象了内核与用户态之间的内存拷贝操作（copy_from_user 和 copy_to_user），处理不同 OS 内存管理模型的差异。
• RknpuSchedulerRuntime：抽象了调度器所需的 OS 运行时能力，包括创建等待原语（new_waiter）、创建 Worker 唤醒信号（new_worker_signal）、生成后台 Worker 线程（spawn_worker）以及在硬件执行或调度停滞时的出让机制（yield_now）。

3. 多尺度 workload 的 Benchmark 测试

设计并执行覆盖多种场景的基准测试，包括：

• tiny_dispatch（极小任务调度）
• mid_balanced（中等规模平衡负载）
• throughput_heavy（重吞吐负载）
• llama_decode_like（模拟大模型解码负载）

实现结果

1. 调度模型与并发机制成功运行

成功实现了基于 Worker 线程和任务信号量的调度模型。底层通过 RknpuWorkerSignal 和 RknpuSubmitWaiter 实现了可靠的两阶段休眠与唤醒机制，彻底解决了用户态提交与底层硬件执行的深度耦合，多进程争抢 NPU 时的调度变得更加平滑。

2. 驱动 crate 化解耦完成

完成 rknpu crate 的重构，成功将平台强相关的内存拷贝、设备锁等待以及线程调度抽离到 RknpuPlatform trait 中。这证明了驱动的主体逻辑能够以纯库（Library）的形式独立演进，大幅提升了后续移植和维护的工程效率。

3. Benchmark 测试与多核性能验证

完成了全量 Benchmark 测试。结合日志数据，得出了明确的结论：在中大型任务场景下，多核并行已经能够稳定地带来明显的正向收益。 具体的几组明确结果如下：

• mid_balanced 场景：1-core 的平均提交时间从 56.158 ms 降到了 3-core 的 39.204 ms，加速比达到了 1.432x，并行效率为 47.75%。
• throughput_heavy 场景：1-core 的平均提交时间从 76.605 ms 降到了 40.824 ms，加速比提升至 1.876x，并行效率达到了 62.55%。
• llama_decode_like 场景：1-core 平均提交时间从 423.358 ms 降到了 231.858 ms，加速比达到 1.826x，并行效率为 60.86%。 结论：数据有力地证明了，在重负载（如吞吐密集型和模拟大模型推理场景）下，当前的 crate 化调度机制和多核分发路径是稳定且具备实战价值的。但在极小任务（如 tiny_dispatch）下，由于调度本身的软件开销，多核加速比不明显甚至可能出现负收益，这也为下阶段（如探索 fast-path 或 batching 提交）指明了优化方向。

RK3588 RKNPU 开发文档

本文档基于 RockChip官方开源仓库和 StarryOS 仓库中对 RK3588 NPU 运行时库（闭源 librknnrt.so）及内核侧 RKNPU DRM 驱动的逆向与复现成果，整理为三个核心章节：

文档结构

来源标注约定

文档中对每条信息标注来源，使用以下标记：

• Linux rknpu 驱动 — 来自Rockchip官方仓库中rk3588-npu内核驱动代码
• rknpu-ioctl.h — 来自 Linux rknpu 驱动include目录的 ioctl 头文件
• StarryOS Rust 驱动 — 来自 drivers/rknpu/src/ 的 Rust 复刻实现
• 逆向推断 — 基于代码行为推断，无官方文档确认

术语速查

RKNN 手册

本栏汇总 RK3588 NPU 的硬件参考与软件接口文档。

硬件手册

NPU 三核架构、数据精度、寄存器位域详解。

硬件手册

IOCTL 协议

DRM_IOCTL_RKNPU_* 命令表、结构体布局、mmap 规则。

IOCTL 协议

任务提交流程

从用户态提交到硬件执行完成的完整时序。

任务提交流程

RKNN 硬件手册

来源：RK3588 TRM Chapter 36 RKNN

本章汇总 RK3588 NPU 硬件相关文档，包括硬件特性概览与完整寄存器参考。

RKNN 硬件特性

• 三核 NPU，支持三核协同 / 双核协同 / 单核独立
• 每核 384KB 内部缓冲，AHB 配置接口 + AXI 数据接口
• 支持 INT4 / INT8 / INT16 / FP16 / BF16 / TF32 多精度推理
• 功能流水线：CNA（卷积）→ CORE（MAC）→ DPU（后处理）→ PPU（池化）
• 激活函数：ReLU / Leaky ReLU / ReLUx / Sigmoid / Tanh / Softmax
• 池化：Average / Max / Min Pooling

完整硬件特性

寄存器图

每个核心拥有独立 64KB 寄存器空间，按功能模块划分：

寄存器总览

RKNN 硬件特性概览

来源：RK3588 TRM Chapter 36 RKNN

RKNN 是专用于神经网络的处理单元，旨在加速人工智能（AI）领域的神经网络运算，涵盖机器视觉和自然语言处理等方向。AI 的应用范围正在不断扩大，目前已在多个领域提供功能支持，包括人脸追踪、手势与肢体追踪、图像分类、视频监控、自动语音识别（ASR）以及高级驾驶辅助系统（ADAS）。

核心特性

功能模块描述

AHB / AXI 接口

AXI 主接口用于从挂载在 SoC AXI 互联总线上的内存中取数据。AHB 从接口用于访问寄存器，进行配置、调试和测试。

神经网络加速引擎（Neural Network Accelerating Engine）

该引擎是神经网络运算的核心处理单元，包含卷积预处理控制器、内部缓冲区、MAC 阵列和累加器。它为识别功能提供并行卷积 MAC 运算，支持 INT4、INT8、INT16、FP16、BF16 和 TF32 数据类型。

数据处理单元（Data Processing Unit, DPU）

数据处理单元主要负责单数据运算，如 Leaky ReLU、ReLU、ReLUx、Sigmoid、Tanh 等激活函数。同时提供 Softmax、转置（Transpose）、数据格式转换等功能。

平面处理单元（Planar Processing Unit, PPU）

平面处理单元在数据处理单元输出之后执行平面操作，支持平均池化（Average Pooling）、最大池化（Max Pooling）、最小池化（Min Pooling）等。

寄存器配置取数单元（Register File Fetch Unit, PC）

寄存器配置取数单元通过 AXI 接口从外部系统内存中获取寄存器配置（即命令流），实现硬件自动配置各功能模块寄存器。

支持的数据精度与算力

支持的推理框架

TensorFlow、Caffe、TFLite、PyTorch、ONNX NN、Android NN 等。

寄存器地图

RK3588 NPU 每个核心（共 3 核）拥有独立的寄存器空间，内部按功能模块划分为以下区域：

地址空间总览

来源说明：地址映射来自 RK3588 TRM Table 1-1 RKNN Address Mapping。

• PC（任务控制器）
• CNA（卷积加速）
• CORE（MAC 核心）
• DPU（数据后处理）
• DPU_RDMA
• PPU（池化）
• PPU_RDMA
• DDMA / SDMA
• GLOBAL（全局使能）

PC 寄存器块（Program Counter / 任务控制器）

基址：CORE_BASE + 0x0000　｜　地址范围：0x0000 ~ 0x0FFF

来源：RK3588 TRM §36.4.3 Detail Registers Description

PC 是 NPU 的命令流执行引擎，负责：从 DMA 地址读取寄存器命令流 → 按序写入各功能模块寄存器 → 触发执行 → 产生完成中断。

RKNN_pc_version（0x0000）

硬件版本寄存器（只读）。驱动通过 version + (version_num & 0xFFFF) 计算完整版本号。

RKNN_pc_version_num（0x0004）

硬件版本号寄存器（只读）。

RKNN_pc_operation_enable（0x0008）

操作使能寄存器。

RKNN_pc_base_address（0x0010）

PC 基址寄存器，指定 DMA 指令流所在的内存地址。

RKNN_pc_register_amounts（0x0014）

每个 task 需要取的寄存器数量。

每条寄存器指令占 64 bit，格式如下：

模块选择位：

示例：64'h0081_0000_007f_0008 将设置各 block 的 op_en（CNA, CORE, ..., PPU_RDMA）。

注意：op_en 强烈建议放在寄存器列表末尾。在 op_en 之前，必须先设置 64'h0041_xxxx_xxxx_xxxx。

RKNN_pc_interrupt_mask（0x0020）

中断掩码寄存器。置 1 使能对应中断。

注意：在 PC 模式下，int_mask 设置的是最后一个 task 的中断掩码。

RKNN_pc_interrupt_clear（0x0024）

中断清除寄存器。写 1 清除对应中断位。

INT_CLEAR_ALL = 0x1FFFF（清除 bit0~bit16 全部中断）rknpu-ioctl.h

RKNN_pc_interrupt_status（0x0028）

中断状态寄存器（经过 mask 后的状态）。

RKNN_pc_interrupt_raw_status（0x002C）

中断原始状态寄存器（未经 mask 的原始状态）。

RKNN_pc_task_con（0x0030）

任务控制寄存器。

RKNN_pc_task_dma_base_addr（0x0034）

任务 DMA 基址寄存器。

RKNN_pc_task_status（0x003C）

任务状态寄存器（只读）。

附：驱动层补充

中断状态归一化（rknpu_fuzz_status()）

StarryOS Rust 驱动 在判定完成前，对 interrupt_status 做如下归一化处理：

含义 逆向推断：每个功能模块有 2 个中断 bit（G0/G1），硬件可能只置其中一个，但驱动判定完成时需要两个都为 1，因此做归一化。

CNA 寄存器块（Convolution Neural-network Accelerator）

基址：CORE_BASE + 0x1000　｜　地址范围：0x1000 ~ 0x1FFF

来源：RK3588 TRM §36.4.3 Detail Registers Description

CNA 是卷积加速单元，包含特征数据加载、权重加载、384KB 内部缓冲（CBUF）、序列扫描控制器（CSC）。

RKNN_cna_s_status（0x1000）

执行器状态寄存器（只读）。

RKNN_cna_s_pointer（0x1004）

寄存器组指针与 ping-pong 控制。

RKNN_cna_operation_enable（0x1008）

操作使能寄存器。写入此寄存器将触发 CNA 模块开始执行。此寄存器及之后的寄存器均为 ping-pong 影子寄存器。

RKNN_cna_conv_con1（0x100C）

卷积控制寄存器 1：精度、模式、反卷积等。

RKNN_cna_conv_con2（0x1010）

卷积控制寄存器 2：kernel 分组、feature grain、CSC 控制。

RKNN_cna_conv_con3（0x1014）

卷积控制寄存器 3：多核模式、空洞卷积、反卷积步长、卷积步长。

RKNN_cna_data_size0（0x1020）

输入特征数据宽高。

RKNN_cna_data_size1（0x1024）

输入特征数据通道数。

RKNN_cna_data_size2（0x1028）

卷积后输出数据宽度。

RKNN_cna_data_size3（0x102C）

卷积后输出数据 surface 模式与总像素数。

RKNN_cna_weight_size0（0x1030）

权重总字节数。

RKNN_cna_weight_size1（0x1034）

单个 kernel 的权重字节数。

RKNN_cna_weight_size2（0x1038）

Kernel 宽高与数量。

RKNN_cna_cbuf_con0（0x1040）

CBUF（内部缓冲）控制寄存器 0：数据/权重复用、Bank 分配。

RKNN_cna_cbuf_con1（0x1044）

CBUF 控制寄存器 1。

RKNN_cna_cvt_con0（0x104C）

输入转换控制寄存器 0：CVT 截断值、符号、舍入、旁路。

RKNN_cna_cvt_con1（0x1050）

输入转换控制 1：第 1 通道的 scale 和 offset。

RKNN_cna_cvt_con2（0x1054）

输入转换控制 2：第 2 通道。

RKNN_cna_cvt_con3（0x1058）

输入转换控制 3：第 3 通道。

RKNN_cna_cvt_con4（0x105C）

输入转换控制 4：第 4 通道。

RKNN_cna_fc_con0（0x1060）

全连接零跳过控制 0。

RKNN_cna_fc_con1（0x1064）

全连接零跳过控制 1。

RKNN_cna_pad_con0（0x1068）

Pad 控制寄存器 0。

RKNN_cna_feature_data_addr（0x1070）

输入特征数据基址。

RKNN_cna_fc_con2（0x1074）

权重数据地址偏移。

RKNN_cna_dma_con0（0x1078）

AXI DMA 控制寄存器 0：burst 长度。

RKNN_cna_dma_con1（0x107C）

行步长（Line stride）。

RKNN_cna_dma_con2（0x1080）

Surface 步长。

RKNN_cna_fc_data_size0（0x1084）

FC 模式下 AXI DMA 的特征输入宽高。

RKNN_cna_fc_data_size1（0x1088）

FC 模式下 AXI DMA 的特征输入通道数。

RKNN_cna_clk_gate（0x1090）

时钟门控控制寄存器。

RKNN_cna_dcomp_ctrl（0x1100）

权重解压控制寄存器。

RKNN_cna_dcomp_regnum（0x1104）

权重解压寄存器数。

RKNN_cna_dcomp_addr0（0x1110）

权重基址。

RKNN_cna_dcomp_amount0~15（0x1140 ~ 0x117C）

权重解压量寄存器，共 16 个，偏移 0x1140 + N×4（N = 0~15）。

RKNN_cna_cvt_con5（0x1180）

按通道 CVT 使能。

RKNN_cna_pad_con1（0x1184）

Pad 值寄存器。

CORE 寄存器块（MAC 核心控制）

基址：CORE_BASE + 0x3000　｜　地址范围：0x3000 ~ 0x3FFF

来源：RK3588 TRM §36.4.3 Detail Registers Description

CORE 模块包含 MAC 阵列和累加器，负责卷积乘累加运算。

RKNN_core_s_status（0x3000）

执行器状态寄存器（只读）。

RKNN_core_s_pointer（0x3004）

寄存器组指针与 ping-pong 控制。

RKNN_core_operation_enable（0x3008）

操作使能寄存器。写入此寄存器将触发 CORE 模块开始执行。此寄存器及之后的寄存器均为 ping-pong 影子寄存器。

RKNN_core_mac_gating（0x300C）

MAC 软时钟门控寄存器。

注意：复位值为 0x07800800，与其他寄存器不同。

RKNN_core_misc_cfg（0x3010）

杂项配置寄存器：精度、深度可分离、量化使能。

RKNN_core_dataout_size_0（0x3014）

输出特征尺寸寄存器 0：宽高。

RKNN_core_dataout_size_1（0x3018）

输出特征尺寸寄存器 1：通道数。

RKNN_core_clip_truncate（0x301C）

截断与舍入控制寄存器。

DPU 寄存器块（Data Processing Unit）

基址：CORE_BASE + 0x4000　｜　地址范围：0x4000 ~ 0x4FFF

来源：RK3588 TRM §36.4.3 Detail Registers Description

DPU 负责后处理运算，包含三级流水线核心：BS CORE（Bias/Scale）→ BN CORE（Batch Norm）→ EW CORE（Element-Wise），以及输出转换器、LUT 引擎、转置/重组等功能。

RKNN_dpu_s_status（0x4000）

执行器状态寄存器（只读）。

RKNN_dpu_s_pointer（0x4004）

寄存器组指针与 ping-pong 控制。

RKNN_dpu_operation_enable（0x4008）

操作使能。写入触发 DPU 执行，此寄存器及之后均为 ping-pong 影子寄存器。

RKNN_dpu_feature_mode_cfg（0x400C）

特征模式配置：flying mode、输出目标、卷积模式、burst、非对齐、转置、重组。

RKNN_dpu_data_format（0x4010）

数据格式配置：输入/输出/处理精度、负数移位值。

RKNN_dpu_offset_pend（0x4014）

额外通道填充值。

RKNN_dpu_dst_base_addr（0x4020）

目标基址。

RKNN_dpu_dst_surf_stride（0x4024）

输出 surface 步长。

RKNN_dpu_data_cube_width（0x4030）

输入 cube 宽度。

RKNN_dpu_data_cube_height（0x4034）

输入 cube 高度 + minmax 控制。

RKNN_dpu_data_cube_notch_addr（0x4038）

Notch 地址（宽度末尾到 shape 行末的像素数）。

RKNN_dpu_data_cube_channel（0x403C）

输入 cube 通道数。

RKNN_dpu_bs_cfg（0x4040）

BS CORE 配置：ALU 算法、操作数来源、ReLU/PRELU/RELUX 控制。

RKNN_dpu_bs_alu_cfg（0x4044）

BS ALU 操作数。

RKNN_dpu_bs_mul_cfg（0x4048）

BS MUL 配置：操作数、移位值、来源。

RKNN_dpu_bs_relux_cmp_value（0x404C）

BS RELUX 比较值。

RKNN_dpu_bs_ow_cfg（0x4050）

BS OW（CPEND）配置 + 重组计数器 + 转置。

RKNN_dpu_bs_ow_op（0x4054）

CPEND 操作数。

RKNN_dpu_wdma_size_0（0x4058）

DPU WDMA 尺寸 0：转置精度、通道。

RKNN_dpu_wdma_size_1（0x405C）

DPU WDMA 尺寸 1：宽高。

RKNN_dpu_bn_cfg（0x4060）

BN CORE 配置：ALU 算法、操作数来源、ReLU/PRELU/RELUX 控制。

RKNN_dpu_bn_alu_cfg（0x4064）

BN ALU 操作数。

RKNN_dpu_bn_mul_cfg（0x4068）

BN MUL 配置。

RKNN_dpu_bn_relux_cmp_value（0x406C）

BN RELUX 比较值。

RKNN_dpu_ew_cfg（0x4070）

EW CORE 配置：ALU 算法（Max/Min/Add/Div/Minus/Abs/Neg/Floor/Ceil）、LUT、转换器、PRELU 等。

RKNN_dpu_ew_cvt_offset_value（0x4074）

EW 输入转换偏移。

RKNN_dpu_ew_cvt_scale_value（0x4078）

EW 转换缩放与移位。

RKNN_dpu_ew_relux_cmp_value（0x407C）

EW RELUX 比较值。

RKNN_dpu_out_cvt_offset（0x4080）

输出转换偏移。

RKNN_dpu_out_cvt_scale（0x4084）

输出转换缩放 + fp32→fp16 使能。

RKNN_dpu_out_cvt_shift（0x4088）

输出转换移位、舍入、指数。

RKNN_dpu_ew_op_value_0~7（0x4090 ~ 0x40AC）

EW CORE 操作数寄存器，共 8 个，偏移 0x4090 + N×4（N = 0~7）。

RKNN_dpu_surface_add（0x40C0）

Surface 加法器。

RKNN_dpu_lut_access_cfg（0x4100）

LUT 访问配置。

RKNN_dpu_lut_access_data（0x4104）

LUT 访问数据。

RKNN_dpu_lut_cfg（0x4108）

LUT 配置。

RKNN_dpu_lut_info（0x410C）

LUT 索引选择。

RKNN_dpu_lut_le_start（0x4110）

RKNN_dpu_lut_le_end（0x4114）

RKNN_dpu_lut_lo_start（0x4118）

RKNN_dpu_lut_lo_end（0x411C）

RKNN_dpu_lut_le_slope_scale（0x4120）

LE LUT 斜率缩放（上溢/下溢）。

RKNN_dpu_lut_le_slope_shift（0x4124）

LE LUT 斜率移位。

RKNN_dpu_lut_lo_slope_scale（0x4128）

LO LUT 斜率缩放。

RKNN_dpu_lut_lo_slope_shift（0x412C）

LO LUT 斜率移位。

DPU_RDMA 寄存器块

基址：CORE_BASE + 0x5000　｜　地址范围：0x5000 ~ 0x5FFF

来源：RK3588 TRM §36.4.3 Detail Registers Description

DPU_RDMA 负责为 DPU 从外部内存读取输入数据，包含四路 DMA 引擎：MRDMA（主数据）、BRDMA（BS 操作数）、NRDMA（BN 操作数）、ERDMA（EW 操作数）。

RKNN_dpu_rdma_s_status（0x5000）

执行器状态寄存器（只读）。

RKNN_dpu_rdma_s_pointer（0x5004）

寄存器组指针与 ping-pong 控制。

RKNN_dpu_rdma_operation_enable（0x5008）

操作使能。写入触发 DPU_RDMA 执行，此寄存器及之后均为 ping-pong 影子寄存器。

RKNN_dpu_rdma_data_cube_width（0x500C）

输入特征宽度。

RKNN_dpu_rdma_data_cube_height（0x5010）

输入特征高度 + EW line notch。

RKNN_dpu_rdma_data_cube_channel（0x5014）

输入特征通道数。

RKNN_dpu_rdma_src_base_addr（0x5018）

Flying 模式源地址。

RKNN_dpu_rdma_brdma_cfg（0x501C）

BRDMA（BS 操作数读取 DMA）配置。

RKNN_dpu_rdma_bs_base_addr（0x5020）

BS 操作数基址。

RKNN_dpu_rdma_nrdma_cfg（0x5028）

NRDMA（BN 操作数读取 DMA）配置。

RKNN_dpu_rdma_bn_base_addr（0x502C）

BN 操作数基址。

RKNN_dpu_rdma_erdma_cfg（0x5034）

ERDMA（EW 操作数读取 DMA）配置。

RKNN_dpu_rdma_ew_base_addr（0x5038）

EW 操作数基址。

RKNN_dpu_rdma_ew_surf_stride（0x5040）

EW 特征图 surface 步长。

RKNN_dpu_rdma_feature_mode_cfg（0x5044）

特征模式配置：精度、burst、组合使用、flying mode、unpooling。

RKNN_dpu_rdma_src_dma_cfg（0x5048）

源 DMA 配置：line notch、unpooling 参数。

RKNN_dpu_rdma_surf_notch（0x504C）

Surface notch。

RKNN_dpu_rdma_pad_cfg（0x5064）

反池化 Pad 配置。

RKNN_dpu_rdma_weight（0x5068）

四路 DMA 仲裁权重。

RKNN_dpu_rdma_ew_surf_notch（0x506C）

EW surface notch。

PPU 寄存器块（Planar Processing Unit）

基址：CORE_BASE + 0x6000　｜　地址范围：0x6000 ~ 0x6FFF

来源：RK3588 TRM §36.4.3 Detail Registers Description

PPU 负责池化运算，支持平均池化、最大池化、最小池化，可与 DPU 流水线级联或独立 flying 模式运行。

RKNN_ppu_s_status（0x6000）

执行器状态寄存器（只读）。

RKNN_ppu_s_pointer（0x6004）

寄存器组指针与 ping-pong 控制。

RKNN_ppu_operation_enable（0x6008）

操作使能。写入触发 PPU 执行，此寄存器及之后均为 ping-pong 影子寄存器。

RKNN_ppu_data_cube_in_width（0x600C）

池化输入 cube 宽度。

RKNN_ppu_data_cube_in_height（0x6010）

池化输入 cube 高度。

RKNN_ppu_data_cube_in_channel（0x6014）

池化输入 cube 通道数。

RKNN_ppu_data_cube_out_width（0x6018）

池化输出 cube 宽度。

RKNN_ppu_data_cube_out_height（0x601C）

池化输出 cube 高度。

RKNN_ppu_data_cube_out_channel（0x6020）

池化输出 cube 通道数。

RKNN_ppu_operation_mode_cfg（0x6024）

操作模式配置：池化方法、flying mode、notch、索引输出。

RKNN_ppu_pooling_kernel_cfg（0x6034）

池化 kernel 大小与步长。

RKNN_ppu_recip_kernel_width（0x6038）

Kernel 宽度倒数（用于平均池化计算）。

RKNN_ppu_recip_kernel_height（0x603C）

Kernel 高度倒数。

RKNN_ppu_pooling_padding_cfg（0x6040）

池化四边 padding。

RKNN_ppu_padding_value_1_cfg（0x6044）

Pad 填充值低 32 位。

RKNN_ppu_padding_value_2_cfg（0x6048）

Pad 填充值高 3 位。

RKNN_ppu_dst_base_addr（0x6070）

输出 cube 目标基址。

RKNN_ppu_dst_surf_stride（0x607C）

输出 surface 步长。

RKNN_ppu_data_format（0x6084）

数据格式配置。

RKNN_ppu_misc_ctrl（0x60DC）

杂项控制：非对齐模式、多 surface 输出、burst。

PPU_RDMA 寄存器块

基址：CORE_BASE + 0x7000　｜　地址范围：0x7000 ~ 0x7FFF

来源：RK3588 TRM §36.4.3 Detail Registers Description

PPU_RDMA 负责为 PPU 从外部内存读取池化输入特征数据（flying 模式下使用）。

RKNN_ppu_rdma_s_status（0x7000）

执行器状态寄存器（只读）。

RKNN_ppu_rdma_s_pointer（0x7004）

寄存器组指针与 ping-pong 控制。

RKNN_ppu_rdma_operation_enable（0x7008）

操作使能。写入触发 PPU_RDMA 执行，此寄存器及之后均为 ping-pong 影子寄存器。

RKNN_ppu_rdma_cube_in_width（0x700C）

池化输入 cube 宽度。

RKNN_ppu_rdma_cube_in_height（0x7010）

池化输入 cube 高度。

RKNN_ppu_rdma_cube_in_channel（0x7014）

池化输入 cube 通道数。

RKNN_ppu_rdma_src_base_addr（0x701C）

池化 cube 源基址。