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,116 @@
+# ============================================================================
+# cpu21-riscv 流水线 CPU —— 一键重建 Vivado 工程
+#   FPGA：Nexys4DDR / xc7a100tcsg324-1（Vivado 2025.2 实测通过）
+#
+# 目录结构（本脚本所在目录就是工程目录）：
+#   create_project.tcl      本脚本
+#   srcs/rtl/*.v            处理器 RTL（顶层 cpu21_riscv_redirect_int_bpb）
+#   srcs/board/*.v|*.vh     板级顶层、片内 ROM 初始化（含 __FAST 仿真版本）
+#   srcs/constrs/*.xdc      引脚约束与板级母版
+#   srcs/tb/*.v             测试平台（中断/分支预测、无中断、板级）
+#   srcs/rom/*.hex          测试平台加载的 ROM 镜像
+#   tools/、programs/       迷你汇编器与测试程序（改程序、重生成 ROM 用）
+#   说明文档：cpu21_riscv_redirect_int_bpb说明.md
+#
+# 用法：
+#   1) 建议先删掉本目录下的 pipelined-cpu.xpr，以及 *.runs / *.sim / *.cache /
+#      *.hw / *.gen / *.ip_user_files 等生成目录（不删会在下面报错提示）；
+#   2) 在 Vivado Tcl Shell 里执行：  source create_project.tcl
+#      或命令行：  vivado -mode batch -source create_project.tcl -log create.log
+#   3) 工程就地创建：pipelined-cpu.xpr（源文件仍在 srcs/ 下，不会被搬动）。
+#
+# 脚本用 [info script] 定位自身目录，所以整个文件夹拷到任何路径都能直接用。
+# 若想用 Vivado 自动生成的版本，见说明文档“工程分享”一节。
+# ============================================================================
+
+set origin_dir [file dirname [file normalize [info script]]]
+set proj_name  "pipelined-cpu"
+set part_name  "xc7a100tcsg324-1"
+
+# ---------------------------------------------------------------- 自检
+set required [list \
+  "$origin_dir/srcs/board/cpu21_board_top.v" \
+  "$origin_dir/srcs/board/cpu21_board_rom.vh" \
+  "$origin_dir/srcs/board/cpu21_board_rom_fast.vh" \
+  "$origin_dir/srcs/constrs/cpu21_board_top.xdc" \
+  "$origin_dir/srcs/tb/tb_cpu21_riscv_redirect_int_bpb.v" \
+  "$origin_dir/srcs/tb/tb_no_intr.v" \
+  "$origin_dir/srcs/tb/tb_board_top.v"]
+set missing {}
+foreach f $required { if {![file exists $f]} { lappend missing $f } }
+if {[llength [glob -nocomplain "$origin_dir/srcs/rtl/*.v"]] == 0} {
+  lappend missing "$origin_dir/srcs/rtl/*.v"
+}
+if {[llength $missing] > 0} {
+  puts "ERROR: 缺少下列文件，请确认 srcs/ 目录完整："
+  foreach f $missing { puts "   $f" }
+  return 1
+}
+
+if {[file exists "$origin_dir/$proj_name.xpr"]} {
+  puts "ERROR: 工程已存在：$origin_dir/$proj_name.xpr"
+  puts "       请先删除 .xpr（以及 *.runs / *.sim 等生成目录）后重跑本脚本。"
+  return 1
+}
+
+# ---------------------------------------------------------------- 建工程
+create_project $proj_name $origin_dir -part $part_name
+
+# 设计源文件：处理器 RTL + 板级顶层 + 片内 ROM 初始化
+add_files -norecurse -fileset sources_1 [glob "$origin_dir/srcs/rtl/*.v"]
+add_files -norecurse -fileset sources_1 [list \
+  "$origin_dir/srcs/board/cpu21_board_top.v" \
+  "$origin_dir/srcs/board/cpu21_board_rom.vh"]
+set_property file_type {Verilog Header} \
+  [get_files "$origin_dir/srcs/board/cpu21_board_rom.vh"]
+
+# 扫雷程序的 ROM 初始化（由 saolei/tools/build.ps1 生成，可能还不存在）。
+# 综合/仿真时定义宏 SAOLEI_ROM 就会用它替换上面的跑马灯 ROM。
+set saolei_rom "$origin_dir/srcs/board/cpu21_saolei_rom.vh"
+if {[file exists $saolei_rom]} {
+  add_files -norecurse -fileset sources_1 [list $saolei_rom]
+  set_property file_type {Verilog Header} [get_files $saolei_rom]
+} else {
+  puts "NOTE: 还没有 $saolei_rom —— 需要先跑 saolei/tools/build.ps1 生成"
+}
+
+# 约束（cpu21_board_top.xdc 是引脚与分频时钟约束）
+add_files -norecurse -fileset constrs_1 [glob "$origin_dir/srcs/constrs/*.xdc"]
+
+# 仿真文件：测试平台 + ROM 镜像 + 快速版 ROM 头文件
+add_files -norecurse -fileset sim_1 [list \
+  "$origin_dir/srcs/tb/tb_cpu21_riscv_redirect_int_bpb.v" \
+  "$origin_dir/srcs/tb/tb_no_intr.v" \
+  "$origin_dir/srcs/tb/tb_board_top.v" \
+  "$origin_dir/srcs/board/cpu21_board_rom_fast.vh"]
+add_files -norecurse -fileset sim_1 [glob "$origin_dir/srcs/rom/*.hex"]
+set_property file_type {Verilog Header} \
+  [get_files "$origin_dir/srcs/board/cpu21_board_rom_fast.vh"]
+
+# 第二个仿真 fileset：无中断测试平台（tb_no_intr）
+create_fileset -simset sim_2
+add_files -norecurse -fileset sim_2 [list \
+  "$origin_dir/srcs/tb/tb_no_intr.v" \
+  "$origin_dir/srcs/tb/tb_cpu21_riscv_redirect_int_bpb.v"]
+
+# ---------------------------------------------------------------- 顶层与顺序
+set_property top cpu21_board_top                 [get_filesets sources_1]
+set_property top tb_cpu21_riscv_redirect_int_bpb [get_filesets sim_1]
+set_property top tb_no_intr                      [get_filesets sim_2]
+update_compile_order -fileset sources_1
+update_compile_order -fileset sim_1
+update_compile_order -fileset sim_2
+
+# GUI 仿真默认只跑 1000 ns，这里改成跑完（否则看起来像卡住）
+foreach fs {sim_1 sim_2} {
+  catch { set_property -name {xsim.simulate.runtime} -value {all} -objects [get_filesets $fs] }
+}
+
+# ---------------------------------------------------------------- 结果汇总
+puts "工程已创建：$origin_dir/$proj_name.xpr"
+puts "  sources_1 顶层 = cpu21_board_top（上板：时钟分频 + 片内 ROM/RAM + 引脚）"
+puts "  sim_1     顶层 = tb_cpu21_riscv_redirect_int_bpb（中断/分支预测）"
+puts "  sim_2     顶层 = tb_no_intr（指令集测试，ROM 镜像在 srcs/rom/）"
+puts "  下一步：Run Synthesis → Run Implementation → Generate Bitstream，或 Run Simulation"
+puts "  提示：CPU 时钟 = 100 MHz / CLK_DIV（默认 2）= 50 MHz；改分频比时"
+puts "        cpu21_board_top.v 的 CLK_DIV 与 cpu21_board_top.xdc 的 -divide_by 要一起改。"