feat(starryos): add K230 KPU QEMU support

[Joshua912815]

问题背景

当前 dev 分支缺少面向 QEMU K230 的 StarryOS 启动与 KPU/NPU 暴露路径。QEMU 侧 zevorn/qemu 的 chao-k230-dev 分支已经提供 K230 机器和 KPU 模型，Kunos 仓库也给出了可参考的 K230 direct boot、DTB 和 SD rootfs 参数；但 StarryOS 侧还没有对应的平台 crate、K230 board/qemu 配置、SDHCI rootfs 注册路径，以及用户态访问 KPU 的 /dev 接口。

本 PR 是第一阶段适配，目标是先打通 QEMU K230 上 StarryOS 的启动、rootfs 挂载和 KPU 基础设备访问，并补充可由 Starry test-suit 运行的 /dev/kpu 用户态 smoke 回归用例。当前范围不包含真实 KPU command stream 的端到端推理验证。

主要变更

1. 新增 drivers/npu/k230-kpu no_std 驱动 crate

   • 固化 KPU CFG/L2 地址、寄存器 offset、done status、control value、IRQ、ioctl 和 mmap offset。
   • 提供 CommandRange、命令流地址拆分、program_command、run_command、clear_done、start、status、wait_done 等基础接口。
   • 校验命令流范围不能为空，且不能跨 4GiB window，避免无法用单个 COMMAND_HI 表达。

2. 新增 platforms/ax-plat-riscv64-k230

   • 对齐 QEMU K230 direct boot 的内存、UART0、timer、PLIC、CLINT、KPU、SD0/SD1 地址。
   • 增加 K230 启动页表、console、timer、irq、power、memory 等平台实现。
   • 静态注册 SDHCI1 block 设备，使 QEMU -drive if=sd,... 挂载的 rootfs 能被 StarryOS 识别。
   • SDHCI1 使用 sdhci-host + sdmmc-protocol 初始化 SD card，并通过 rd-block 接入 block device；第一阶段使用 FIFO transfer，先保证 QEMU rootfs 基础读写路径稳定。

3. StarryOS 新增 KPU 设备节点

   • 新增 /dev/kpu 和 /dev/kpu0，设备号为 240:1。
   • 支持 32-bit 对齐的 KPU CFG read/write。
   • 支持 status、clear、program command、start、run、wait done ioctl。
   • 支持 mmap KPU CFG 与 KPU L2，便于后续用户态准备 command stream 和访问 KPU L2。

4. 新增 K230 board/qemu 配置

   • 新增 os/StarryOS/configs/board/k230-canmv.toml。
   • 新增 k230-canmv.dts 与生成后的 k230-canmv.dtb，补充 KPU 节点和 timebase-frequency = 27000000。
   • 新增 os/StarryOS/configs/qemu/qemu-k230.toml，使用 -machine k230、direct boot、DTB 和 -drive if=sd,...。

5. 接入构建与平台选择

   • starryos 新增 k230 feature，联动 ax-hal/riscv64-k230 与 starry-kernel/k230-kpu。
   • axhal 新增 riscv64-k230 平台 feature 和 build.rs 平台 crate 选择。
   • axbuild 识别 riscv64-k230 平台。

6. 修正 axbuild rootfs QEMU patch 策略

   • 当 QEMU 参数已有 -drive if=sd,... 时，只替换该 SD drive 的 file=。
   • 不再为 K230 额外注入 VirtIO block/net 默认参数，避免破坏 SD1 rootfs 路径。
   • 增加单测覆盖 SD drive patch 行为。

7. 新增 K230 专用 Starry test-suit smoke

   • 新增 test-suit/starryos/k230-qemu/qemu-k230/kpu-smoke。
   • 该组独立于默认 normal，因为它依赖带 -machine k230 和 KPU model 的 QEMU binary。
   • C asset pipeline 构建并安装 /usr/bin/k230-kpu-smoke。
   • 用例覆盖 /dev/kpu 和 /dev/kpu0 open、KPU CFG pread()、status/clear ioctl、CFG mmap status 读取、L2 mmap 32-bit 写入/读回，并以 KPU_SMOKE_PASS 作为稳定成功 marker。

8. 新增详细阶段报告

   • docs/k230-kpu-qemu-adaptation.md 记录任务背景、QEMU/KPU 事实、总体架构、实现细节、设备 ABI、SDHCI/rootfs 适配、用户态 smoke、问题定位过程、验证矩阵和后续计划。

关键设计理由

• KPU 寄存器和命令流编程逻辑放在独立 no_std crate 中，避免 StarryOS VFS glue 与硬件语义混在一起，后续可复用到测试或其他 OS glue。
• K230 rootfs 使用 QEMU SD1，而不是常规 QEMU virt 的 VirtIO block，因此平台侧必须注册 SDHCI1，axbuild 也必须保留 if=sd drive。
• KPU CFG、FFT、AI2D 在 QEMU 地址图中相邻且小于 4KiB，按子页粒度分别声明会在页表映射时重复映射；因此平台配置将这段合并为 [0x8040_0000, 0x2000]。
• 当前阶段优先使用 SDHCI FIFO transfer 和轮询 done，减少 DMA/IRQ 变量，先把启动、rootfs 和基础 KPU ABI 打通。
• K230 QEMU smoke 单独成组，而不是放入默认 normal，避免默认 CI 在没有 K230 QEMU 的环境里误跑；需要验证 K230 时显式选择 --test-group k230-qemu。

验证

默认实验环境为 Docker/Linux，镜像为 starryos-dev:ubuntu-qemu10.2.1。

已通过：

cargo fmt --check
cargo test -p k230-kpu
cargo test -p axbuild ensure_disk_boot_net_patches_sd_drive_without_adding_virtio
cargo xtask clippy --package k230-kpu
cargo xtask clippy --package ax-plat-riscv64-k230
cargo xtask clippy --package axbuild
cargo xtask starry build -c os/StarryOS/configs/board/k230-canmv.toml --arch riscv64

已按 K230 实际 target 参数通过 starryos target clippy：

AX_CONFIG_PATH=/mnt/tmp/axbuild/axconfig/starryos/riscv64gc-unknown-none-elf/.axconfig.toml \
CARGO_UNSTABLE_JSON_TARGET_SPEC=true \
AX_PLATFORM=riscv64-k230 \
AX_ARCH=riscv64 \
AX_LOG=info \
AX_TARGET=riscv64gc-unknown-none-elf \
cargo clippy -p starryos \
  --target scripts/targets/no-pie/riscv64gc-unknown-none-elf.json \
  -Z unstable-options \
  --target-dir /mnt/target \
  --features ax-hal/riscv64-k230,k230 \
  -Z json-target-spec \
  -Z build-std=core,alloc \
  --bin starryos \
  --release \
  -- -D warnings

已使用 /Users/joshua/tmp/qemu 中 chao-k230-dev 分支构建出的 QEMU K230 binary 做手动 smoke 验证，确认：

• StarryOS 能通过 QEMU K230 direct boot 启动。
• k230-sdhci1 成功注册为 block device。
• ax-fs-ng 能从 SD raw ext4 rootfs 挂载根文件系统。
• 系统能进入 StarryOS 用户态 shell。
• guest 中 /dev/kpu 与 /dev/kpu0 均存在，设备号为 240:1。
• guest 中 od -An -tx4 -N4 /dev/kpu 可读取 KPU CFG 寄存器，当前读数为 00000000。

已通过新增 test-suit 用例：

PATH="$PWD/target/qemu-k230/bin:$PATH" \
cargo xtask starry test qemu --test-group k230-qemu --arch riscv64 -c kpu-smoke

结果：

PASS kpu-smoke
result: 1/1 case(s) passed
all starry k230-qemu qemu tests passed

当前限制与后续计划

• 本 PR 尚未包含真实 KPU command stream 的端到端推理验证。
• /dev/kpu ABI 仍是第一阶段低层 ABI，后续需要补充用户态头文件或 Rust 绑定。
• KPU completion 当前提供轮询等待路径，后续可根据 QEMU 模型和真实需求接入 IRQ/event/poll。
• 当前验证目标是 QEMU K230，不等价于物理 K230 板卡验证。
• 下一阶段建议引入最小真实 command stream 或 KModel fixture，继续复用 k230-qemu test group 覆盖 run/wait done 与推理结果读取。

[ZR233]

riscv64 平台和 快设备驱动正在重构，可稍等1天再继续这部分

[ZR233]

#961 #976

[mai-team-app]

PR #994 Review: feat(starryos): add K230 KPU QEMU support

变更概述

本 PR 新增 K230 KPU QEMU 支持，包括：

• drivers/npu/k230-kpu no_std 驱动 crate（KPU 寄存器、命令流编程、ioctl/mmap 接口）
• platforms/ax-plat-riscv64-k230 静态平台 crate（直接启动、页表、PLIC、SDHCI1 块设备）
• StarryOS /dev/kpu 设备节点
• K230 board/qemu 配置文件
• axbuild SD drive patch 逻辑

阻塞问题：与已合并 PR #961 及进行中 PR #976 存在根本性冲突

1. PR #961 已合并进 dev，riscv64 平台架构方向已改变

PR #961（feat(riscv64): support dynamic platform on QEMU and SG2002，26 commits，169 files）已于 2026-05-27T14:09:19Z 合并入 dev。该 PR 引入了 plat-dyn/plat-static 平台选择模型：

• riscv64 QEMU 默认和测试配置已切换到 plat-dyn（FDT 动态探测）
• ax-driver 收敛为 plat-static/plat-dyn 两种模式
• PLIC 注册、IRQ 处理、块设备初始化均已重构

本 PR 使用旧的静态平台方式（plat_dyn = false），新建 ax-plat-riscv64-k230 crate 遵循的模式已被 dev 替换。K230 在 plat-dyn 体系下应考虑通过 FDT 探测设备（KPU、SDHCI 等），而不是新增一个完全静态的平台 crate。

当前 PR 与 dev 存在合并冲突（Cargo.lock、os/StarryOS/starryos/Cargo.toml），且 mergeable_state: dirty。

2. PR #976 仍在进行中，块设备驱动架构即将重构

PR #976（refactor(rdif-block): switch block drivers to submit poll，36 commits，103 files）正在进行中。该 PR：

• 移除 rd-block / rd-block-volume
• 将 SD/MMC 块设备适配到新的 rdif-block submit/poll 模型
• 修复 SDHCI DMA 同步顺序和 IRQ status 缓存 bug

本 PR 的 SDHCI 块设备实现（drivers.rs）直接依赖 rd_block::Interface、rd_block::IQueue、rd_block::Request 等接口，这些接口将在 PR #976 合并后被移除。如果本 PR 先合并，PR #976 合并时将产生大量冲突。

3. 项目成员已明确提醒

ZR233（MEMBER）已在本 PR 评论区指出："riscv64 平台和快设备驱动正在重构，可稍等1天再继续这部分"，并链接了 PR #961 和 PR #976。

代码质量观察（非阻塞，供后续重写参考）

• k230-kpu 驱动 crate 本身质量良好：no_std、有单元测试、命令流范围校验清晰
• axbuild SD drive patch 逻辑（replace_sd_drive_arg）设计合理，有对应单测
• KPU 设备节点 ioctl/mmap 设计合理
• boot.rs 页表映射、irq.rs PLIC 处理逻辑在旧架构下是正确的

本地验证结果（在 PR 分支上）

• cargo fmt --check：通过
• cargo test -p k230-kpu：3/3 通过
• cargo test -p axbuild：408/408 通过
• 合并冲突确认：Cargo.lock、os/StarryOS/starryos/Cargo.toml
• 无 GitHub Actions CI 运行记录

建议

1. 等待 PR #976 合并后再继续，避免块设备驱动冲突
2. 基于最新 dev（含 PR #961）重新适配，考虑 K230 是否应使用 plat-dyn + FDT 探测，而不是新建静态平台 crate
3. 将 SDHCI 块设备实现适配到 PR #976 引入的新 rdif-block submit/poll 模型
4. k230-kpu 驱动 crate 和 KPU 设备节点代码可以在重写时保留，它们与平台架构和块设备驱动解耦

Powered by mimo-v2.5-pro

[mai-team-app]

PR #994 Review: feat(starryos): add K230 KPU QEMU support

变更概述

本 PR 新增 K230 KPU QEMU 第一阶段适配，包括：

• drivers/npu/k230-kpu no_std 驱动 crate（KPU 寄存器、命令流编程、ioctl/mmap 接口）
• platforms/ax-plat-riscv64-k230 静态平台 crate（direct boot、页表、PLIC、SDHCI1 块设备）
• StarryOS /dev/kpu 设备节点
• K230 board/qemu 配置文件
• axbuild SD drive patch 逻辑
• K230 QEMU smoke test-suit 用例

PR 质量整体较高：k230-kpu 驱动设计清晰、有单元测试、命令流范围校验合理；KPU 设备节点 ABI 设计规范；axbuild SD drive patch 有单测覆盖。但存在阻塞性架构冲突。

🔴 阻塞问题

1. riscv64 平台架构已变更，本 PR 使用旧模式

PR #961（feat(riscv64): support dynamic platform on QEMU and SG2002）已于 2026-05-27 合并入 dev。该 PR 引入了 plat-dyn/plat-static 平台选择模型，riscv64 QEMU 默认已切换到 plat-dyn（FDT 动态探测）。本 PR 新建 ax-plat-riscv64-k230 使用 plat_dyn = false 的静态方式，与 dev 当前架构方向不一致。建议基于最新 dev 重新适配，评估 K230 是否应采用 plat-dyn + FDT 探测。

2. 块设备驱动架构即将重构

PR #976（refactor(rdif-block): switch block drivers to submit poll）正在进行中，将移除 rd-block/rd-block-volume，切换到新的 rdif-block submit/poll 模型。本 PR 的 SDHCI 块设备实现直接依赖 rd_block::Interface、rd_block::IQueue 等即将被移除的接口。如果本 PR 先合并，PR #976 合并时将产生大量冲突。

3. 合并冲突

当前 mergeable_state: dirty，Cargo.lock 和 os/StarryOS/starryos/Cargo.toml 存在冲突，需要 rebase。

🟢 质量亮点

• k230-kpu crate：no_std、有单元测试（3/3 通过）、命令流范围校验清晰
• KPU 设备节点 ioctl/mmap ABI 设计规范
• axbuild replace_sd_drive_arg 逻辑合理，有对应单测（408/408 通过）
• 阶段报告文档详尽（845 行）

📋 建议

1. 等待 PR #976 合并后再继续适配 SDHCI 块设备
2. 基于最新 dev（含 PR #961）重新适配，评估 K230 使用 plat-dyn + FDT 探测的可行性
3. SDHCI 块设备适配到 PR #976 引入的新 rdif-block submit/poll 模型
4. k230-kpu 驱动 crate 和 KPU 设备节点代码可以在重写时保留，它们与平台架构和块设备驱动解耦

本地验证

• cargo test -p k230-kpu：3/3 通过
• cargo test -p axbuild：408/408 通过
• 合并冲突已确认

Powered by mimo-v2.5-pro

[ZR233]

请迁移至 riscv64 动态平台