这个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 驱动开发进展。

第一周开发日志（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(())
}
}

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 源基址。

RKNN_ppu_rdma_src_line_stride（0x7024）

源行步长（shape 宽度）。

RKNN_ppu_rdma_src_surf_stride（0x7028）

源 surface 步长（shape 面积）。

RKNN_ppu_rdma_data_format（0x7030）

输入数据格式。

DDMA / SDMA 寄存器块（Data DMA / System DMA）

DDMA 基址：CORE_BASE + 0x8000　｜　地址范围：0x8000 ~ 0x8FFF SDMA 基址：CORE_BASE + 0x9000　｜　地址范围：0x9000 ~ 0x9FFF

来源：RK3588 TRM §36.4.3 Detail Registers Description

DDMA 和 SDMA 寄存器布局完全一致，仅基址不同（DDMA 0x8xxx，SDMA 0x9xxx）。DDMA 用于数据搬运，SDMA 用于系统级搬运。以下以 DDMA 为例展开位域，SDMA 将偏移 0x8xxx 替换为 0x9xxx 即可。

cfg_outstanding（DDMA: 0x8000 / SDMA: 0x9000）

读写 outstanding 数配置。

rd_weight_0（DDMA: 0x8004 / SDMA: 0x9004）

读仲裁权重 0：各模块读 burst 权重。

wr_weight_0（DDMA: 0x8008 / SDMA: 0x9008）

写仲裁权重。

cfg_id_error（DDMA: 0x800C / SDMA: 0x900C）

错误 ID 记录。

rd_weight_1（DDMA: 0x8010 / SDMA: 0x9010）

读仲裁权重 1：PC 读 burst 权重。

cfg_dma_fifo_clr（DDMA: 0x8014 / SDMA: 0x9014）

清除 DMA FIFO。

cfg_dma_arb（DDMA: 0x8018 / SDMA: 0x9018）

DMA 仲裁模式配置。

cfg_dma_rd_qos（DDMA: 0x8020 / SDMA: 0x9020）

各模块读 QoS 配置。

cfg_dma_rd_cfg（DDMA: 0x8024 / SDMA: 0x9024）

AXI 读通道信号配置。

cfg_dma_wr_cfg（DDMA: 0x8028 / SDMA: 0x9028）

AXI 写通道信号配置。

cfg_dma_wstrb（DDMA: 0x802C / SDMA: 0x902C）

AXI 写选通。

cfg_status（DDMA: 0x8030 / SDMA: 0x9030）

DMA 状态。

dt_wr_amount（DDMA: 0x8034 / SDMA: 0x9034）

数据写入量统计。用于 ioctl GetDtWrAmount。

dt_rd_amount（DDMA: 0x8038 / SDMA: 0x9038）

数据读取量统计。用于 ioctl GetDtRdAmount。

wt_rd_amount（DDMA: 0x803C / SDMA: 0x903C）

权重读取量统计。用于 ioctl GetWtRdAmount。

清除操作：写 rd_weight_1(0x8010) 值 0x80000101 再写 0x00000101（两次写入进行 latch/clear）。

GLOBAL 寄存器块（全局使能）

基址：CORE_BASE + 0xF000　｜　地址范围：0xF000 ~ 0xFFFF

来源：RK3588 TRM §36.4.3 Detail Registers Description

GLOBAL 模块仅包含一个寄存器，用于一次性组合使能各功能模块的操作。

RKNN_global_operation_enable（0xF008）

组合操作使能：一次写入同时触发多个模块开始执行。

IOCTL 协议与数据结构

本章整理 RKNPU 驱动的全部 ioctl 命令、传参结构体布局、flags 枚举，以及 mmap(offset) 编码规则。

1. IOCTL 命令表

RKNPU 驱动提供 6 个 ioctl 命令，同时定义了两套编号：

1.1 两套编号的区别

rknpu-ioctl.h 中 RKNPU_IOC_MAGIC = 'r'，DRM_COMMAND_BASE 来自 <libdrm/drm.h>（通常为 0x40）。

2. 结构体布局

2.1 struct rknpu_action（8 字节）

用于 ACTION ioctl，查询/设置各种属性。

2.2 struct rknpu_mem_create（40 字节）

StarryOS Rust 驱动 扩展了额外字段：iommu_domain_id: i32、core_mask: u32，用于多核/IOMMU 域管理。

2.3 struct rknpu_mem_map（16 字节）

2.4 struct rknpu_mem_destroy（16 字节）

2.5 struct rknpu_mem_sync（32 字节）

2.6 struct rknpu_task（36 字节，__packed）

单个任务描述，由 PC 命令流引擎解释执行。