feat(saolei): 新增纯 C 扫雷（MMIO 显示 + 中断读鼠标），扩展 CPU 外设并清理仓库

## 背景在原有五级流水 CPU 的基础上，用一颗 RISC-V 工具链把"纯 C 写的扫雷"编译成机器码固化进片内 ROM 运行，并为此把 MMIO 外设从"只有一个 LED 寄存器"扩展成显示（VGA 显存）+ 七段数码管 + 鼠标事件（含中断）的完整子系统。原 LED MMIO 的语义保持不变，原有跑马灯/中断/指令回归不受影响。 ## 硬件（pipelined-cpu/srcs） - cpu21_mmio.v：扩展成 MMIO 中枢，新增 * 七段数码管寄存器（0x1004，8 位十六进制） * 鼠标寄存器组（0x1100+）：STATUS/DATA/ACK/CTRL/INPUT/TIME/FRAME/EVCNT/LEVEL/MAGIC —— 含 16 项事件 FIFO 与 mouse_irq_o（读空自动回 0，不丢事件） * 显示控制器（0x1140+）：CTRL（光标可见/背景色）、CURSOR（列、行） * 显存窗口（0x2000-0x27FF）：写端口输出到板级顶层的双口 RAM，读保持组合读 * LEVEL（0x1120）：软件中断寄存器，写 1 拉起 level_irq_o（用作"关卡入口"） * 地址译码、字节写合并、读数据 mux 全部按原风格实现 - 新增外设 RTL：cpu21_vga.v（640x480@60 按格子扫描，8x8 字模放大 2 倍）、 cpu21_seg7.v（8 位数码管动态扫描）、cpu21_pointer.v（5 向按键→鼠标事件，1 ms 去抖 + 事件排队）、cpu21_ps2_mouse.v（可选真鼠标，PS/2 11 位帧接收 + 3 字节包解析） - cpu21_riscv_redirect_int_bpb.v：新增外设总线端口（显存写/读回、鼠标事件输入、中断输出、数码管数据、帧脉冲），例化扩展后的 cpu21_mmio - cpu21_board_top.v：接入显存双口 RAM + VGA + 数码管 + 鼠标事件源，中断接线为 irq_i = {SW2, LEVEL|SW1, 鼠标|SW0}；ROM 宏切换（定义 SAOLEI_ROM 加载扫雷程序）； ROM_WORDS 1024→8192 - cpu21_board_top.xdc：新增按键、SW[3]、8 位数码管、VGA、PS/2 的全部引脚约束 - tb_board_top.v：新端口显式接 0/1，避免悬空影响原跑马灯回归 - create_project.tcl：把 cpu21_saolei_rom.vh 按 Verilog Header 条件加入 ## 软件（saolei/） - sw/mmio.h：全部 MMIO 地址与格子编码（换地址只改这一个文件） - sw/saolei.c：纯 C 扫雷 —— 背景"伪操作系统" main()（开始界面）+ 关卡 level_main() （在 IRQ1 里跑完整局）+ 棋盘位图/布雷（首点安全）/BFS 展开/插旗/胜负判定/逐格绘制 - sw/isr.c：**中断读鼠标的代码**。三个固定地址入口： * isr1_entry（.text.isr1=0x100）关卡入口：保存全部调用者保存寄存器 + csrrsi 打开 MIE（让鼠标中断可嵌套）→ level_main * isr2_entry（.text.isr2=0x200）鼠标读取：只存 ra → 纯 C 主体 isr_body * isr3_entry（.text.isr3=0x300）备用：直接 uret - sw/start.c：设 sp、清 .bss、进 main（只有这一处必要内联汇编） - sw/linker.ld：复位 0x0、三个中断入口 0x100/0x200/0x300、栈顶 0x0FFC；用 ASSERT 禁止 .data/.rodata（这颗核读不到 ROM 里的数据） ## 构建与工具链适配（saolei/tools） - build.ps1：一键 C → .o → ELF → .hex + cpu21_saolei_rom.vh，任一步失败立刻停止 - check_isa.py：用"指令白名单"逐条检查反汇编，出现本核未实现的指令即报错并给修复提示 - elf2hex.py：裸二进制 → $readmemh hex + ROM 初始化头文件 - 三处针对本核的关键配置（都已写进脚本注释）： 1) -march=rv32im_zicsr（GCC 15 起 rv32im 不含 Zicsr，csrrsi 会报错） 2) 不能禁链接器松弛：gcc 函数调用默认是 auipc+jalr，靠松弛压成 jal，禁掉后 35 条 auipc 会留在代码里（本核没有 auipc）；用 -msmall-data-limit=0 防止松弛引入 gp 相对寻址 3) 中断入口地址必须写在段声明上（.text.isr1 0x100 : ...），只写 ". = 0x100;" 会被 ld 忽略（实测 isr1 掉到了 0x14） - 实测结果：text=3368B、data=0、bss=1436B，842 条指令全部通过 ISA 检查，入口地址 _start=0x0 / isr1_entry=0x100 / isr2_entry=0x200 / isr3_entry=0x300 ## 仓库清理 - 删除被工程取代的 saolei/hw、saolei/constrs（外设已并入 srcs/rtl） - 删除全部 Vivado 生成物：.xpr、.runs、.sim、.cache、.hw、.ip_user_files、.Xil、 vivado.jou/log —— 需要工程时用 source create_project.tcl 一键重建（约 0.3 MB 源文件） - .gitignore 增加 saolei/build/（构建产物可一键重建） ## 文档 - README：更新目录结构、仓库约定（不放生成物）、MMIO 地址表、文件与模块划分表、上板说明，新增"扫雷程序（saolei/）"章节 - saolei/README.md：重写 —— 程序结构（背景/关卡/鼠标 + 三个中断入口）、本核指令子集与对应写法、构建步骤与实测数据、MMIO 地址表、上板/仿真步骤、操作说明、验证状态与已知可改进项 ## 验证状态（如实说明） - 已实测：C 工具链链路（编译/链接/ISA 检查/hex 生成/入口地址逐条核对） - 未验证：所有 RTL 未经综合与仿真（本机无 Vivado），C 程序也未在仿真器/硬件上运行过；建议先跑 tools/run_regress.ps1 确认原回归仍全 PASS，再用 SAOLEI_ROM 宏做行为仿真
2026-09-16 20:11:00 +08:00
commit f50639e90f
66 changed files with 19733 additions and 0 deletions
@@ -0,0 +1,129 @@
+/* -----------------------------------------------------------------------------
+ * isr.c —— 中断服务程序：从 MMIO 读鼠标事件（**这就是"中断读鼠标操作的指令"**）
+ *
+ * 这颗核的中断硬件行为（见 srcs/rtl/cpu21_riscv_irq_ctrl.v）：
+ *   * irq_i 上升沿 -> 挂起位置 1；响应中断时硬件自动清挂起位、清 ustatus[0]（MIE）、
+ *     把返回地址压进内部 EPC 栈；
+ *   * 从 uepc 返回用 `uret`（编码 0x00200073，不在标准 C 里，只能内联汇编）；
+ *   * **硬件不保存任何通用寄存器**，所以软件必须自己保证不破坏被打断的代码。
+ *
+ * 因此这里分了三个固定地址的入口 + 一个纯 C 主体：
+ *   1) isr1_entry（.text.isr1 = 0x100）：**关卡（游戏）入口**，调 level_main()。
+ *      游戏是一整段会调用别的函数的 C 程序，所以入口把**所有调用者保存寄存器**
+ *      （ra、t0-t6、a0-a7）都存起来，并用 csrrsi 打开 MIE 让鼠标中断能嵌套；
+ *   2) isr2_entry（.text.isr2 = 0x200）：**鼠标读取**，只存 ra 后调下面的 isr_body；
+ *   3) isr3_entry（.text.isr3 = 0x300）：备用，直接 uret；
+ *   4) isr_body：**纯 C**，本文件用 -ffixed-x1,x5..x7,x10..x17,x28..x31 编译，
+ *      逼 GCC 只用 s0-s11（callee-saved，函数自己会存/恢复）和 sp，于是被打断的
+ *      代码的调用者保存寄存器绝对不会被破坏 —— 这样主体就是安全的纯 C 叶子函数。
+ *
+ * 主体要做的事：把硬件事件 FIFO（深度 16）里的项全部搬到软件环形队列，
+ * 主循环再从队列里取。FIFO 读空后中断线自动回 0，下一个事件会重新产生上升沿，
+ * 所以不会丢事件。
+ * ---------------------------------------------------------------------------*/
+#include "mmio.h"
+
+/* ---- 与 saolei.c 共用的软件事件队列（定义在这里，声明在 mmio.h） ---- */
+volatile unsigned g_evq[EVQ_SIZE];
+volatile unsigned g_evq_head; /* 主循环消费 */
+volatile unsigned g_evq_tail; /* 中断生产 */
+volatile unsigned g_evq_lost; /* 队列满丢弃计数（调试） */
+
+/* 中断主体：纯 C 叶子函数（不调用任何函数），只使用 s 寄存器和 sp。
+ * 编译本文件时必须加 -ffixed-x1 -ffixed-x5..x7 -ffixed-x10..x17 -ffixed-x28..x31
+ * （见 tools/build.ps1），否则它会用到调用者保存寄存器从而破坏被打断的代码。 */
+__attribute__((used, noinline)) void isr_body(void);
+
+void isr_body(void)
+{
+    unsigned ev, next;
+
+    /* 硬件 FIFO 非空就一直搬（STATUS[0] = 非空） */
+    while ((REG_R(REG_STATUS) & 1u) != 0u)
+    {
+        ev = REG_R(REG_MDATA); /* lw：{btn[20:16], dy[15:8], dx[7:0]} */
+        next = (g_evq_tail + 1u) & EVQ_MASK;
+        if (next != g_evq_head)
+        {
+            g_evq[g_evq_tail] = ev;
+            g_evq_tail = next;
+        }
+        else
+        {
+            g_evq_lost = g_evq_lost + 1u; /* 软件队列满：丢弃并计数 */
+        }
+        REG_W(REG_MACK) = 1u; /* sw：弹出硬件 FIFO 一项 */
+    }
+}
+
+/* ---------------------------------------------------------------------------
+ * 三个中断入口，分别在链接脚本固定住的 0x100 / 0x200 / 0x300。
+ *
+ * IRQ1 = 0x100：**关卡（游戏）入口**。游戏是一整段会调用别的函数的 C 程序，
+ *   所以入口必须把**所有调用者保存寄存器**（ra、t0-t6、a0-a7）都存起来，
+ *   否则返回时会把被打断的背景程序弄坏。进入中断时硬件已把 MIE 清 0，这里再
+ *   重新打开，鼠标中断（IRQ2 优先级更高）才能嵌套进来；uret 时硬件会从内部
+ *   栈里恢复原来的 MIE。
+ * IRQ2 = 0x200：**鼠标读取**。C 主体用 -ffixed 编译（只用 s 寄存器和 sp），
+ *   所以入口只要保存 ra。
+ * IRQ3 = 0x300：备用（保留给拨码开关等外部源）。
+ * ------------------------------------------------------------------------- */
+extern void level_main(void);
+
+__attribute__((naked, section(".text.isr1"), used, noinline)) void isr1_entry(void)
+{
+    __asm__ volatile(
+        "addi sp, sp, -64\n\t"
+        "sw ra,  0(sp)\n\t"
+        "sw t0,  4(sp)\n\t"
+        "sw t1,  8(sp)\n\t"
+        "sw t2, 12(sp)\n\t"
+        "sw t3, 16(sp)\n\t"
+        "sw t4, 20(sp)\n\t"
+        "sw t5, 24(sp)\n\t"
+        "sw t6, 28(sp)\n\t"
+        "sw a0, 32(sp)\n\t"
+        "sw a1, 36(sp)\n\t"
+        "sw a2, 40(sp)\n\t"
+        "sw a3, 44(sp)\n\t"
+        "sw a4, 48(sp)\n\t"
+        "sw a5, 52(sp)\n\t"
+        "sw a6, 56(sp)\n\t"
+        "sw a7, 60(sp)\n\t"
+        "csrrsi x0, 0x004, 1\n\t" /* ustatus[0]=MIE：允许鼠标中断嵌套 */
+        "jal ra, level_main\n\t"
+        "lw a7, 60(sp)\n\t"
+        "lw a6, 56(sp)\n\t"
+        "lw a5, 52(sp)\n\t"
+        "lw a4, 48(sp)\n\t"
+        "lw a3, 44(sp)\n\t"
+        "lw a2, 40(sp)\n\t"
+        "lw a1, 36(sp)\n\t"
+        "lw a0, 32(sp)\n\t"
+        "lw t6, 28(sp)\n\t"
+        "lw t5, 24(sp)\n\t"
+        "lw t4, 20(sp)\n\t"
+        "lw t3, 16(sp)\n\t"
+        "lw t2, 12(sp)\n\t"
+        "lw t1,  8(sp)\n\t"
+        "lw t0,  4(sp)\n\t"
+        "lw ra,  0(sp)\n\t"
+        "addi sp, sp, 64\n\t"
+        "uret\n\t");
+}
+
+__attribute__((naked, section(".text.isr2"), used, noinline)) void isr2_entry(void)
+{
+    __asm__ volatile(
+        "addi sp, sp, -8\n\t" /* 保存被打断代码的 ra（jal 会覆盖它） */
+        "sw   ra, 0(sp)\n\t"
+        "jal  ra, isr_body\n\t" /* 调纯 C 主体（它自己保存 s 寄存器） */
+        "lw   ra, 0(sp)\n\t"
+        "addi sp, sp, 8\n\t"
+        "uret\n\t"); /* 从 uepc 返回：这颗核的中断返回指令 */
+}
+
+__attribute__((naked, section(".text.isr3"), used, noinline)) void isr3_entry(void)
+{
+    __asm__ volatile("uret\n\t");
+}