G233 exper manual

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

专业阶段 SoC 方向的实验围绕 G233 虚拟开发板的板级建模与外设驱动展开，你需要按照 G233 SoC 硬件手册 给出的硬件参数，完成板卡实例化、GPIO/PWM/WDT 外设建模、SPI 控制器与 Flash 存储器件互联等实验任务。

环境搭建¶

第一步，安装 QEMU 开发环境，请参考导学阶段的 Step0: 搭建 QEMU 开发环境。

第二步，点击这里，自动 fork 作业仓库到 GTOC 组织下面，该仓库会为你开通代码上传权限。

第三步，需要 clone 刚刚 fork 好的仓库到本地：

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

# 比如 github 用户名是 zevorn，那么命令如下：
# git clone git@github.com:gevico/qemu-camp-2026-soc-zevorn.git

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

git remote add upstream git@github.com:gevico/gevico-classroom-qemu-camp-2026-soc-qemu-camp.git

同步上游代码变更的常用命令：

git pull upstream main --rebase

第五步，配置编译选项：

cd qemu
./configure --target-list=riscv64-softmmu \
            --extra-cflags="-O0 -g3" \
            --enable-rust

提交代码¶

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

SoC 方向使用 QEMU 的 QTest 测试框架。QTest 测题在宿主机侧编译和运行，通过 QTest 协议与 QEMU 进程通信，直接读写 MMIO 寄存器（qtest_readl / qtest_writel）来验证设备模型的行为，无需编写客户机程序。

你需要熟读每个测题源码，理解每个测题的测试意图，并实现对应的 QEMU 建模功能（需要修改 QEMU 本体源码，非测题源码），文末会给出具体实验的介绍，辅助你阅读测题源码。

每次实验完成后，需要将你的代码提交到你的 fork 仓库中。

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

测评验收¶

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

make check-gevico-qtest

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 分，评分将显示到训练营的专业阶段排行榜。

实验介绍¶

SoC 方向的全部实验围绕 G233 虚拟开发板的板级建模与外设驱动展开，涵盖板卡实例化、GPIO 输入输出与中断、PWM 波形输出、WDT 看门狗超时、SPI 控制器与 Flash 读写等功能。

所有外设的地址映射、寄存器定义和编程模型，详见 G233 SoC 硬件手册。

所有实验的测题，均在 tests/gevico/qtest/ 目录下，以 test- 开头的 .c 文件。

实验一 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。