项目计划更新 — K3 (SpacemiT Key Stone) 实体板适配

日期：2026-05-28（2026-05-30 修订）变更：取消 VisionFive2 (JH7110) 移植计划，转投 SpacemiT K3 平台修订：补充 RTOS 外设驱动规划、机器人应用 Demo 场景、8 月决赛演示方案

一、变更原因

从 VisionFive2 (JH7110) 迁移到 SpacemiT K3，两个原因：

JH7110 核心内部资料不透明 — U74 (SiFive) 为 IP 核，内部微架构文档封闭，底层调试和驱动优化受限
K3 AI 性能远优于 VF2 — 8× A100 提供 60 TOPS 算力，本地跑 30B 大模型；而 VF2 无任何 AI 加速

此外 K3 内置双核 RT24 小核，RT24 专跑 rt-async（单核 M-mode），X100 大核跑 StarryOS，大小核物理隔离，实时性能不受 AI 负载影响。

特性	VF2 方案 (废弃)	K3 方案 (采用)
实时核	从 X100 大核中抠一个 hart	RT24 独立小核 (物理隔离)
大核负担	实时 hart 抢占 StarryOS 时间	X100 全部 8 核跑 StarryOS/AI
实时确定性	受乱序执行 + 缓存抖动影响	6 级顺序核，确定性延迟
AI 算力	无	60 TOPS (8× A100, 本地跑 30B 模型)
核间 IPI	软件自实现 (CLINT MSIP)	ACLINT MSIP (同机制，换地址)
中断控制器	PLIC + CLINT	ACLINT + APLIC (RISC-V AIA)
UART	共享 1×	独立：主域 17× + RT 域 6×
GPIO	有限	5 组 (128 线) + RT 域独立 GPIO
内存	8GB LPDDR4	最高 32GB LPDDR5 (51 GB/s)
实时定时器	CLINT mtime	专用 Timer 单元 (多组) + Watchdog

核心优势：小核负责电机控制、传感器采集等微秒级实时任务；大核跑 AI 推理、视觉处理、StarryOS 用户态应用——两者通过本项目的 AMP 通信方案（ov-channels + ov-rpc）协作，延迟极低且互不干扰。

二、K3 硬件架构与地址映射摘要

2.1 系统整体架构

┌─────────────────────────────────────────────────────────────────────────┐
│                           应用层                                         │
│    机器人控制 · AI 推理 · 视觉识别 · 传感器采集 · 用户交互                 │
├──────────────────────────────┬──────────────────────────────────────────┤
│                              │                                          │
│   X100 × 8 (StarryOS)        │        RT24 × 1 (rt-async)              │
│   ┌────────────────────┐     │     ┌────────────────────┐               │
│   │  StarryOS 用户态 App   │     │     │  实时任务 (async)   │              │
│   │  AI 推理 · 规划决策  │     │     │  电机 · 传感器 · PWM│              │
│   └────────┬───────────┘     │     └────────┬───────────┘               │
│            │ mmap + ioctl    │              │                           │
│   ┌────────┴───────────┐     │              │                           │
│   │  /dev/rt_shm 驱动   │     │     ┌────────┴───────────┐             │
│   │  (StarryOS 内核)    │     │     │  Chip / TimerChip   │             │
│   └────────┬───────────┘     │     │  (rt-async platform) │             │
│            │                 │     └────────┬───────────┘             │
├────────────┼─────────────────┼──────────────┼──────────────────────────┤
│            │    本项目 AMP 通信方案          │                          │
│            │                 │              │                          │
│  ┌─────────┴─────────────────┴──────────────┴───────────────┐          │
│  │              ov-channels  (共享内存无锁通道)               │          │
│  │              ov-rpc       (postcard 序列化 RPC)            │          │
│  │              SHM 区域     (SRAM 512KB 或 DDR)             │          │
│  └─────────────────────────┬────────────────────────────────┘          │
│                            │ IPI 通知                                   │
│  ┌─────────────────────────┴────────────────────────────────┐          │
│  │  K3:  ACLINT MSIP 写寄存器 (与 QEMU CLINT MSIP 同机制)    │          │
│  └─────────────────────────┬────────────────────────────────┘          │
├────────────────────────────┼───────────────────────────────────────────┤
│              K3 SoC 硬件    │                                           │
│  ┌─────────────────────────┴────────────────────────────────┐          │
│  │  Main CPU Domain          │  RT CPU Domain                │          │
│  │  X100 × 8  (乱序, 2.4GHz) │  RT24 × 2  (顺序, RV64GC)    │          │
│  │  A100 × 8  (60 TOPS AI)   │  独立 UART × 6 / GPIO / PWM  │          │
│  │  8MB L2 共享缓存          │  独立中断源 (int_src[])       │          │
│  │  ACLINT + APLIC (AIA)     │  可访问 X100 域设备窗口       │          │
│  └───────────────────────────┴──────────────────────────────┘          │
│           共享内存: SRAM (512KB) · DDR (≤32GB LPDDR5)                  │
│  DDR (≤32GB LPDDR5) · UART (主域17×+RT域6×) · CAN ×10                  │
│  SPI ×6 · I2C ×9 · GPIO (128线) · PCIe ×8 · USB 3.0 ×5               │
│  GMAC ×4 · PWM ×30 · Mailbox ×16 · Spinlock ×32                       │
└─────────────────────────────────────────────────────────────────────────┘

数据流：用户态 App → mmap 共享内存 → ov-channels 写入消息 → ACLINT MSIP IPI 通知 RT24 → rt-async 异步任务处理 → 响应原路返回。

2.2 关键地址映射

RT 域 (RCPU Domain) — rt-async 运行在 RT24 单核上 (M-mode)

模块	地址	大小	备注
SRAM (512KB)	`0xC080_0000`	512KB	与主域 `0xC080_0000` 共享
X100 域设备窗口	`0x8000_0000`	~1GB	RT 域可访问主域设备
sys_ctrl	`0xC088_0000`	4KB	系统控制寄存器
R_UART0~5	`0xC088_1000` ~ `0xC088_1500`	256B/ea	RT 域专用 UART
R_GPIO	`0xC088_9400`	1KB	RT 域 GPIO
AON_TIMER1	`0xC088_9000`	1KB	Always-On 定时器
AON_TIMER2~4	`0xC088_C800` ~ `0xC088_CA00`	256B/ea	额外定时器
PWM0~9	`0xC088_D100` ~ `0xC088_DA00`	256B/ea	PWM 输出
R_SSP0~2 (SPI)	`0xC088_5000` ~ `0xC088_5200`	256B/ea	SPI 控制器
R_I2C0~1	`0xC088_6000` ~ `0xC088_6100`	256B/ea	I2C 控制器
R_MAILBOX	`0xC076_0000`	64KB	RT 域 Mailbox (SoC 提供，后续可选用)
DDR DRAM	`0x01_0000_0000`	64GB	通过地址映射访问主存

2.3 中断架构

K3 使用 RISC-V AIA (Advanced Interrupt Architecture)：

ACLINT：每个 hart 的软件中断 (MSIP) + 定时器中断 (MTIMER) — 与 QEMU CLINT 同机制
APLIC：外部中断控制器，MSI-only 输出，最多 1023 个中断源

RT 域中断源（关键字段）：

中断号	信号	用途
int_src[8~10]	timer_{1,2,3}_irq	GP Timer 中断
int_src[17~21]	shub_uart_int[0~4]	RT UART 中断
int_src[49]	aud_gpio_int_ap	RT GPIO 中断
int_src[46~48]	timer2_{1,2,3}_irq	Timer2 中断
int_src[76~81]	timer3/4 中断	额外定时器
int_src[65~66]	mailbox_irq0[0~1]	Mailbox0 中断 (可选用)
int_src[67]	ap_spinlock_irq	Spinlock 解锁中断 (可选用)

2.4 RT24 核心特性（rt-async 运行在此核）

基于 CVA6 (OpenHW Group 开源核心)
6 级顺序单发射流水线 — 确定性执行，适合实时
支持 RV64IMAFDC (RV64GC) 完整指令集
三级特权：M / S / U — rt-async 运行于 M-mode，独占整个 RT24 核
支持 SV39 虚拟内存 (ITLB + DTLB + PTW)
超低待机与运行功耗 — 不与大核争抢功耗预算
独立外设集 (RCPU Domain)：自有 UART × 6、GPIO、Timer、I2C、SPI 等，不与大核争用
可通过地址窗口访问 X100 域设备 (0x8000_0000) — 用于 Mailbox 等 SoC 共享资源
与 X100 域共享 SRAM (0xC080_0000, 512KB) 和 DDR — 这是双核通过共享内存通信的基础
K3 有 2 个 RT24 核，计划只用 1 个跑 rt-async，另 1 个留做系统管理或备用

三、修订后的项目阶段计划

阶段一：RTOS 内核完善（5月12日 - 6月15日）

[x] JoinHandle<T>
[ ] Mutex 优先级继承
[ ] 基础同步原语完善

阶段二：双内核通信（6月1日 - 6月30日）

[x] ov-channels 共享内存通信 (Notification + Message Queue)
[x] ov-rpc 调用框架（多通道、多调用模式：call / call_quiet / send / urgent）
[x] amp.toml 统一配置（地址自动生成）
[x] StarryOS rt_shm 设备驱动
[ ] 性能基准测试报告

阶段三：K3 实体板移植与驱动（6月15日 - 7月31日）

取代原 VisionFive2 (JH7110) 移植计划

3.1 平台基础设施

[ ] K3 启动流程研究
- [ ] RT24 核独立启动方式 (M-mode entry, 不依赖 X100 域)
- [ ] RT24 与 X100 域的启动时序协调 (谁先启动？握手协议？)
- [ ] 链接脚本适配 (RCPU 域地址映射，区别于 QEMU virt)
- [ ] SRAM (512KB) 与 DDR 内存布局规划 — rt-async 代码放 SRAM 还是 DDR？
[ ] RT24 裸机运行环境搭建
- [ ] riscv64 target 配置 (RT24 为 RV64GC, 含 F/D 扩展 — 区别于 QEMU 的 imac)
- [ ] 最小 M-mode 启动代码 (set up stack, mtvec, 跳入 rust main)
- [ ] UART 控制台输出 (R_UART0 @ 0xC088_1000, 16550 兼容)

3.2 核心驱动适配

[ ] 定时器驱动
- [ ] AON Timer (替代 CLINT mtime，作为 rt-async 系统 tick)
- [ ] GP Timer 1~3 (高精度 deadline / 周期任务)
- [ ] 定时器频率获取与校准
[ ] 中断控制器适配
- [ ] 从 PLIC 切换到 APLIC (MSI-only 模式)
- [ ] ACLINT MSIP — 与 QEMU CLINT MSIP 同机制，换基址即可
- [ ] RT 域中断向量表 (int_src[] 映射)

3.3 外设驱动（机器人控制所需）

目标：为 RT24 核心提供控制机器人硬件的驱动能力，使 rt-async 上的异步任务能直接操作电机、传感器等外设。

[ ] GPIO 驱动 (R_GPIO @ 0xC088_9400)
- [ ] 基本 IO 读写
- [ ] 中断模式 (int_src[49] aud_gpio_int_ap)
[ ] PWM 驱动 (PWM0~9)
- [ ] 频率 / 占空比配置
- [ ] 用于电机速度控制、舵机角度控制
[ ] I2C 驱动 (R_I2C0~1 @ 0xC088_6000 ~ 0xC088_6100)
- [ ] 主模式读写 (Master TX/RX)
- [ ] 用于读取 IMU (加速度计/陀螺仪)、距离传感器等
[ ] SPI 驱动 (R_SSP0~2 @ 0xC088_5000 ~ 0xC088_5200)
- [ ] 全双工主模式
- [ ] 用于高速传感器通信 (编码器、ADC 等)
[ ] UART 驱动 (R_UART0~5)
- [ ] 中断收发 (int_src[17~21])
- [ ] 用于调试串口 / 与外部模块通信 (蓝牙、GPS 等)

3.4 AMP 通信方案迁移

本项目已实现的 AMP 通信架构（QEMU virt 上验证通过）：

X100 (StarryOS)                           RT24 (rt-async)
┌──────────────────┐                      ┌──────────────────┐
│  用户态 App       │                      │                  │
│  mmap(/dev/rt_shm)│◄────共享内存────────►│  ov-channels     │
│  ov-rpc / ioctl   │   (ov-channels)      │  ov-rpc          │
├──────────────────┤                      ├──────────────────┤
│  rt_shm 驱动      │◄──── IPI 通知 ──────►│  Chip::pend()    │
│  (mmap + ioctl)   │   CLINT MSIP (QEMU)  │  send_ipi_to_    │
└──────────────────┘                      │  StarryOS()         │
                                          └──────────────────┘

迁移到 K3，整个通信方案不变，仅底层寄存器地址不同：

层次	QEMU virt (当前)	K3 (迁移)
数据通路	ov-channels (共享内存)	ov-channels — 不变
RPC 框架	ov-rpc (postcard 序列化)	ov-rpc — 不变
用户态接口	`/dev/rt_shm` (mmap + ioctl)	`/dev/rt_shm` — 不变
IPI 通知	CLINT MSIP 写寄存器	ACLINT MSIP 写寄存器 (同机制)
定时器	CLINT mtime	AON Timer + GP Timer
中断控制器	PLIC	APLIC (AIA)
共享内存位置	QEMU phys mem 固定区域	SRAM (512KB) 或 DDR

阶段四：实验展示（7月15日 - 8月10日）

向评委量化展示 RTOS 实时核的价值。

外设驱动（PWM/I2C/SPI）作为能力展示。

4.1 RTOS 侧：实时仿真控制任务

[ ] 定义仿真 RPC 服务

ignore

define_service! {
    pub ControlService {
        SET_TARGET:  0 => send  set_target(pos: i32);
        STOP:        1 => urgent stop();
        GET_STATE:   2 => call  get_state() -> (i32, i32);
    }
}

[ ] 周期控制任务 (1kHz 软件仿真)
- [ ] rt-async 定时器驱动 1ms 周期循环
- [ ] 每轮：读取目标 → PID 计算 → 记录输出与时间戳
- [ ] 通过 UART 输出时间戳序列，供 StarryOS 侧分析抖动
[ ] urgent 急停响应测试
- [ ] StarryOS 侧发送 urgent → 测量 RT24 从收到 IPI 到停机的延迟
- [ ] 对比 StarryOS 侧直接处理的延迟

4.2 StarryOS 侧：控制端 + 数据可视化

[ ] 用户态控制 App
- [ ] 通过 ov-rpc call 下发目标 / 读取状态
- [ ] 通过 ov-rpc send 持续推送设定值
- [ ] 通过 ov-rpc urgent 触发急停
[ ] 实时性数据采集与可视化
- [ ] 采集 RTOS 侧的周期时间戳，绘制控制周期抖动图
- [ ] 采集 IPC 往返延迟（StarryOS 发请求 → RTOS 响应 → StarryOS 收到）
- [ ] 生成对比图表（详见 4.4）

4.3 跨核设备操控演示（驱动 + RPC 联动）

通过 StarryOS 侧 ov-rpc 远程操控 RT24 上的 UART / I2C 设备，端到端验证"Linux 下命令 → AMP RPC → RTOS 驱动 → 硬件响应"全链路。

[ ] RPC 服务定义

ignore

define_service! {
    pub DeviceService {
        UART_WRITE: 0 => send  uart_write(data: [u8; 64]);
        UART_READ:  1 => call  uart_read() -> [u8; 64];
        I2C_WRITE:  2 => send  i2c_write(addr: u8, data: [u8; 16]);
        I2C_READ:   3 => call  i2c_read(addr: u8, len: u8) -> [u8; 16];
        STOP:       4 => urgent stop();
    }
}

[ ] UART 演示：StarryOS 用户态通过 ov-rpc 向 RT24 UART 发送字符串 → RT24 通过 R_UART 输出到串口终端 → 看到打印内容
[ ] I2C 演示：StarryOS 用户态通过 ov-rpc 读写 RT24 上的 AT24C02 EEPROM → 写入数据 → 读回验证 → 返回结果
[ ] 证明点：Linux 侧无需自带 I2C/UART 驱动，通过 RPC 即可透明操控 RT 域外设

4.4 实验设计（核心展示）

核心问题：为什么需要 RTOS 实时核？

通过对比实验回答，全部可在 K3 板上复现：

实验一：控制周期确定性

方法	描述	预期结果
StarryOS 直接控制	用户态 timerfd 1ms 周期循环	抖动大 (100us~ms 级)，受调度/GC 影响
RTOS 控制	rt-async 定时器 1ms 周期循环	抖动 < 10us，确定性执行

[ ] 两侧各跑 10000 个周期，导出时间戳
[ ] 绘制 jitter 直方图 / 时序图，直观对比

实验二：负载下实时性退化

步骤	操作	观察
1	StarryOS 空闲，RTOS 运行控制循环	基线：RTOS 周期抖动极小
2	StarryOS 启动 CPU 压力测试 (stress-ng)	RTOS 周期抖动不变
3	StarryOS 启动 AI 推理负载	RTOS 周期抖动仍不变
4	对比：StarryOS 自己跑控制循环 + 同等负载	周期抖动急剧恶化

[ ] 证明物理隔离的核心价值：大核负载不影响小核实时性

实验三：IPC 延迟

场景	描述
`call` 延迟	StarryOS 发请求 → IPI → RTOS 处理 → IPI → StarryOS 收响应
`urgent` 延迟	StarryOS 发急停 → IPI → RTOS 执行 → 测量端到端时间
吞吐量	连续 N 次 `call`，测平均延迟和 P99

[ ] 不同负载下的延迟分布（空闲 / CPU 压力 / AI 推理）
[ ] 证明 IPC 机制在负载下稳定

阶段五：决赛交付与答辩（8月10日 - 8月12日）

[ ] K3 板上稳定运行：X100 大核 (StarryOS) + RT24 小核 (rt-async 实时)
- 备选：若 K3 硬件未到，QEMU virt 演示 + K3 驱动代码展示
[ ] 通过本项目的 AMP 通信方案（ov-channels + ov-rpc + 共享内存 + ACLINT IPI）实现跨核通信
[ ] 实验演示
- [ ] 实验一：控制周期确定性对比
- [ ] 实验二：负载下实时性不退化
- [ ] 实验三：IPC 延迟与吞吐量
- [ ] 自动化实验脚本一键复现
[ ] 驱动能力展示
- [ ] 跨核设备操控：StarryOS 通过 ov-rpc 远程读写 Rt-Async 的 UART / I2C (AT24C02)
- [ ] PWM 波形 / UART 输出
- [ ] 证明 RTOS 驱动层完整可用
[ ] 实时性指标：RT24 抢占延迟、IPC 往返延迟、控制周期抖动、负载下退化程度

四、参考资源

K3 User Manual (PDF) — 完整手册
K3 Brief (PDF)
K3 Overview (中文)
RISC-V AIA Specification — ACLINT + APLIC 规范
CVA6 Open Source Core — RT24 基于 CVA6

项目计划更新 — K3 (SpacemiT Key Stone) 实体板适配 ​

一、变更原因 ​

二、K3 硬件架构与地址映射摘要 ​

2.1 系统整体架构 ​

2.2 关键地址映射 ​

RT 域 (RCPU Domain) — rt-async 运行在 RT24 单核上 (M-mode) ​

2.3 中断架构 ​

2.4 RT24 核心特性（rt-async 运行在此核） ​

三、修订后的项目阶段计划 ​

阶段一：RTOS 内核完善（5月12日 - 6月15日） ​

阶段二：双内核通信（6月1日 - 6月30日） ​

阶段三：K3 实体板移植与驱动（6月15日 - 7月31日） ​

3.1 平台基础设施 ​

3.2 核心驱动适配 ​

3.3 外设驱动（机器人控制所需） ​

3.4 AMP 通信方案迁移 ​

阶段四：实验展示（7月15日 - 8月10日） ​

4.1 RTOS 侧：实时仿真控制任务 ​

4.2 StarryOS 侧：控制端 + 数据可视化 ​

4.3 跨核设备操控演示（驱动 + RPC 联动） ​

4.4 实验设计（核心展示） ​

阶段五：决赛交付与答辩（8月10日 - 8月12日） ​

四、参考资源 ​