面向智能机器人的 AIOS —— StarryOS 在 SG2002 网球拾取机器人上的启动与推理链路(初赛/第一阶段)

本作品完成赛题第一阶段的全部目标:在 SG2002(RISC-V C906)机器人开发板上启动基于 Rust 的组件化操作系统内核 StarryOS,运行开源机器人用户态程序 akars(网页遥控 + USB 摄像头 + 机械臂/电机串口控制),并通过板载 TPU 加载 YOLOv8 网球检测模型完成推理。

在此基础上,我们对上游内核仓库 tgoskits(基线 commit 705e148)做了 6 处实际的工程修改,核心成果是免串口自动引导:通过逆向官方 U-Boot 的默认环境,用 uEnv.txt 覆盖其 sdboot 变量,使板卡上电即自动启动 StarryOS——此前每次启动都必须接串口打断倒计时手敲三条引导命令。

一、成果清单

内容	位置
对 tgoskits 的代码修改(6 文件 + patch)	`tgoskits-changes/`
可烧录 SD 卡镜像(自动引导 StarryOS)	`deploy/sdcard_diy.img`
编译产物:内核 FIT 镜像 / 设备树	`deploy/starryos.uimg`、`deploy/aka-00-sg2002.dtb`
设计文档	`设计文档.md`
技术报告	`技术报告.md`
完整开发过程记录(含全部踩坑与排错)	`操作记录.md`
复现脚本(编译/镜像/固件等)	`build.sh`、`make_sdcard.sh`、`fetch_firmware.sh` 等

二、代码修改摘要(基于 tgoskits commit 705e148)

文件	修改内容
`container/Dockerfile`	补装 `u-boot-tools` + `device-tree-compiler`。官方编译容器缺 `mkimage`,sg2002 目标的 `cargo xtask starry build` 在 uImage 打包步骤必然失败
`scripts/axbuild/src/starry/build.rs`	① 生成 uImage 前预检 `mkimage` 是否存在,给出可操作的报错;② 生成后自动 `mkimage -l` 校验 FIT 的 Load/Entry 地址非 0(地址为 0 时 U-Boot `bootm` 跳转 0 地址,板上表现为 instruction access fault,极难排查;现在构建期即失败)
`scripts/axbuild/src/starry/build/tests.rs`	上述校验逻辑的 3 个单元测试(全部通过)
`os/StarryOS/configs/board/aka-00-sg2002-uEnv.txt`	免串口自动引导配置。原理:官方 U-Boot `bootcmd` 先 `env import` p1 分区的 `uEnv.txt` 再 `run sdboot`,故覆盖 `sdboot` 即接管启动;任一加载步骤失败自动回落官方内核,不会变砖
`scripts/mksdcard-aka00.sh`	一键构建可启动 SD 镜像(FAT32 引导分区 + 4KiB 块、关闭 orphan_file 的 ext4 rootfs),打包前拒绝地址为 0 的内核
`docs/docs/build/sg2002-sd-image.md`	镜像布局、uEnv 机制与常见启动故障的文档

三、运行说明

3.1 环境准备

任意 Linux(或 Windows + WSL2)+ Docker:

docker pull ghcr.io/rcore-os/tgoskits-container:latest

3.2 编译内核

git clone https://github.com/rcore-os/tgoskits && cd tgoskits
git checkout 705e14824519fe519d6e79df1ef1a8fad1dd0e2b
git apply /path/to/tgoskits-changes/contest-stage1.patch

bash /path/to/fetch_firmware.sh

docker run --rm -v "$PWD":/work -w /work ghcr.io/rcore-os/tgoskits-container:latest \
  bash -lc 'cargo xtask starry build -c os/StarryOS/configs/board/aka-00-sg2002.toml'
# 产物: target/riscv64gc-unknown-linux-musl/release/starryos.uimg
# 构建末尾会自动校验 Load/Entry = 0x80200000

3.3 制作 SD 卡镜像

# fip.bin 从 LicheeRV Nano 官方镜像 p1 分区提取
# (校验: 440832 字节, sha1 5b4d1faf5445a19840c6c502f9c60357f7b92d61)
sudo scripts/mksdcard-aka00.sh \
  -f fip.bin \
  -k target/riscv64gc-unknown-linux-musl/release/starryos.uimg \
  -d os/StarryOS/configs/board/aka-00-sg2002.dtb \
  -r rootfs/ -b boot.sd -o sdcard.img

rootfs 的制备(官方 rootfs 复制 + akars + TPU 运行库 + 模型 + wifi_switch)详见 技术报告.md 第 2 节;也可直接烧录本仓库 deploy/sdcard_diy.img。

3.4 烧录与启动

sudo dd if=sdcard.img of=/dev/sdX bs=4M conv=fsync

插卡上电即自动启动(串口 115200 可观察到 === uEnv.txt: booting StarryOS ===, 最终出现 root@starry: 提示符)。无需任何串口交互;若需手动引导(如调试), 在 U-Boot 倒计时打断后:

fatload  mmc 0:1 0x81000000 aka-00-sg2002.dtb
fatload  mmc 0:1 0x82200000 starryos.uimg
bootm    0x82200000 - 0x81000000

3.5 运行机器人程序与 TPU 模型加载

启动后在 StarryOS shell 中:

# 网页遥控 + 摄像头 + 车/机械臂控制(浏览器访问 http://板卡IP:8080)
akars serve --listen 0.0.0.0:8080 --motor /dev/ttyS1 --arm /dev/ttyS2 --camera /dev/cvi-usb-camera0

# TPU 模型加载与推理(YOLOv8 网球检测, CVI cvimodel 格式)
akars /root/yolov8n_tennis_v2.cvimodel --camera /dev/cvi-usb-camera0 --frames 10

# WiFi 配置(连接热点 / 自建热点)
wifi_switch sta <SSID> <密码>
wifi_switch ap  <SSID>

四、代码原创性说明

内核基线:rcore-os/tgoskits commit 705e148(开源,Apache/MIT);我们的修改见 tgoskits-changes/
用户态程序:BattiestStone4/akars(开源),交叉编译时按其上游文档修正了动态链接器配置
fip.bin(SPL+OpenSBI+U-Boot)与 rootfs 基础:LicheeRV Nano 官方镜像(sipeed 官方发布)
TPU 运行库:sophgo TPU SDK(tpu-sdk-sg200x);WiFi 固件:aic8800 官方固件(构建系统内置 SHA-256 校验)
uEnv.txt 自动引导机制、构建期 FIT 校验、SD 镜像工具链为本队原创