G233 exper manual

本文档是专业阶段 SoC 方向的实验手册。

SoC 方向的核心任务：参照 G233 SoC 硬件手册 中的寄存器定义和编程模型，为 G233 虚拟开发板实现板卡实例化、GPIO/PWM/WDT 外设建模、SPI 控制器与 Flash 存储器件互联。

环境搭建¶

第一步，安装 QEMU 开发依赖。

# Ubuntu 24.04
sudo sed -i 's/^Types: deb$/Types: deb deb-src/' /etc/apt/sources.list.d/ubuntu.sources
sudo apt-get update
sudo apt-get build-dep -y qemu

# 安装 Rust 工具链（版本要求 >= 1.85）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
. "$HOME/.cargo/env"
cargo install bindgen-cli

第二步，点击 GitHub Classroom 邀请链接 加入实验，系统会自动在组织下为你创建专属仓库并赋予 maintainer 权限。

第三步，clone 仓库到本地：

git clone git@github.com:gevico/qemu-camp-2026-exper-<你的 github 用户名>.git

第四步，添加上游远程仓库，用于同步上游代码变更：

git remote add upstream git@github.com:gevico/gevico-classroom-qemu-camp-2026-exper-qemu-camp-2026-exper.git
git pull upstream main --rebase

第五步，配置并编译：

make -f Makefile.camp configure
make -f Makefile.camp build

提交代码¶

所有实验的测题源码，均放在仓库根目录路径： tests/gevico/qtest/ 。

SoC 方向使用 QEMU 的 QTest 测试框架——测题在宿主机侧编译运行，通过 QTest 协议直接读写 MMIO 寄存器（qtest_readl / qtest_writel）来检查设备行为，不需要写客户机程序。

先通读测题源码，搞清楚每道题在测什么，然后去 QEMU 本体里实现对应的设备模型（不要改测题源码）。文末有每道题的简介，帮你快速定位。

实现完成后，提交代码到你的仓库：

git add .
git commit -m "feat: subject..."
git push origin main

测评验收¶

本地运行全部测题的方式：

make -f Makefile.camp test-soc

SoC 方向全部测题通过的情况下，你会看到如下输出：

  TEST    qtest-riscv64/test-board-g233           1/10
  TEST    qtest-riscv64/test-gpio-basic           2/10
  TEST    qtest-riscv64/test-gpio-int             3/10
  TEST    qtest-riscv64/test-pwm-basic            4/10
  TEST    qtest-riscv64/test-wdt-timeout          5/10
  TEST    qtest-riscv64/test-spi-jedec            6/10
  TEST    qtest-riscv64/test-flash-read           7/10
  TEST    qtest-riscv64/test-flash-read-int       8/10
  TEST    qtest-riscv64/test-spi-cs               9/10
  TEST    qtest-riscv64/test-spi-overrun         10/10

如果你想运行某个测例，比如 test-board-g233，可以使用如下命令：

make -C build/tests/gevico/qtest/  run-board-g233

如果你想调试某个测例的设备模型，可以使用 GDB 附加到 QTest 启动的 QEMU 进程。先在一个终端启动测例并暂停：

make -C build/tests/gevico/qtest/ gdbstub-board-g233

同理，你也可以通过 gdbstub- 和 tab 键来查看可以调试的测例。

然后在另一个终端使用 GDB 连接：

gdb -ex "target remote :1234" build/qemu-system-riscv64

每道测题 10 分，一共 10 道测题，共计 100 分，评分将显示到训练营的专业阶段排行榜。

实验介绍¶

实验覆盖：板卡实例化、GPIO 输入输出与中断、PWM 波形输出、WDT 看门狗超时、SPI 控制器与 Flash 读写。地址映射和寄存器定义见 G233 SoC 硬件手册。

测题在 tests/gevico/qtest/ 目录下，文件名以 test- 开头。

实验一 test-board-g233¶

实验二 test-gpio-basic¶

实验三 test-gpio-int¶

实验四 test-pwm-basic¶

实验五 test-wdt-timeout¶

实验六 test-spi-jedec¶

实验七 test-flash-read¶

实验八 test-flash-read-int¶

实验九 test-spi-cs¶

实验十 test-spi-overrun¶

溢出原理：RXNE=1 时继续发送新数据 → 接收缓冲区满 → OVERRUN=1。

进阶实验¶

进阶实验一 为 G233 挂载 virtio-mmio 总线¶

基础实验中 G233 只集成了 GPIO、PWM、WDT、SPI 等片内外设，没有块设备和网卡。virtio-mmio 是 QEMU 为嵌入式平台提供的轻量 virtio 传输层，非常适合挂到 G233 这种无 PCI 的 SoC 上。

挑战目标：在 hw/riscv/g233.c 中预留一段 MMIO 地址空间（推荐 0x1010_0000 起），实例化 8 个 virtio-mmio transport slot，并把它们的中断线汇聚到 PLIC 上。

参考方向：

• 阅读 hw/riscv/virt.c 中 create_virtio_regions 的做法，把 slot 数、步长、中断号抽成 G233 machine 的常量。
• 用 sysbus_create_simple("virtio-mmio", ...) 批量创建，注意每个 slot 间留出足够的步长（通常 0x200 / 0x1000）。
• 更新 DTB（create_fdt 函数）中 virtio_mmio@... 节点，保证 guest 内核能发现设备。

进阶实验二 接入 virtio-blk / virtio-net¶

挑战目标：基于进阶实验一的 virtio-mmio 总线，让 G233 支持块设备与网卡：

qemu-system-riscv64 -M g233 \
    -drive file=rootfs.ext4,format=raw,if=none,id=hd0 \
    -device virtio-blk-device,drive=hd0 \
    -netdev user,id=net0 \
    -device virtio-net-device,netdev=net0

验收标准：

• guest 内能看到 /dev/vda 和 eth0。
• 对 /dev/vda 执行 dd 读写后重启数据保留。
• eth0 通过 user-mode networking 可以 ping 10.0.2.2（QEMU 宿主）。

进阶实验三 跑通 Linux 操作系统¶

挑战目标：让 G233 能够作为标准 riscv64 Linux 的目标板，完整启动到 shell 提示符。

建议步骤：

1. 构建内核：从 kernel.org 获取稳定版 Linux（推荐 ≥ 6.6），开启 CONFIG_SOC_VIRT、virtio-blk/net、串口、devtmpfs，以及 G233 所用中断控制器的支持（PLIC + CLINT）。
2. 构建根文件系统：用 buildroot 或 BusyBox 定制最小镜像，默认 init 进入 /bin/sh。
3. Bootloader：先用 -bios default（OpenSBI）直接加载 kernel Image；进阶可接入 U-Boot 做二级引导。
4. DTB 完备化：补全 create_fdt 中的 CPU、memory、clock、serial、virtio-mmio 节点，并把 bootargs 默认设为 root=/dev/vda rw console=ttyS0 earlycon。

5. 最终启动命令示例：

   qemu-system-riscv64 -M g233 -nographic \
       -bios default -kernel Image \
       -append "root=/dev/vda rw console=ttyS0 earlycon" \
       -drive file=rootfs.ext4,format=raw,if=none,id=hd0 \
       -device virtio-blk-device,drive=hd0
   

验收标准：从加电到进入 shell、能执行 uname -a、ls /dev、cat /proc/cpuinfo 看到正确的 hart 数量；启动日志中可以看到 OpenSBI → Linux 内核自解压 → 用户空间 init 的完整链路。

进阶实验四 扩展 virtio 设备族¶

在前三个进阶实验的基础上，进一步扩展 G233 支持的 virtio 设备：

• virtio-rng：为 Linux 内核提供熵源，缓解 random: crng init done 长时间阻塞。
• virtio-console：作为第二个串口/管理通道。
• virtio-9p：通过 9P 协议把宿主机目录挂载到 guest，便于调试时共享文件。
• virtio-gpu（更高难度）：接入 G233 显示子系统，做最小的 framebuffer 输出。

产出一份说明文档，介绍各 virtio 设备的启动参数、使用方式、以及在 G233 上的性能/兼容性表现。