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 宏做行为仿真
This commit is contained in:
@@ -0,0 +1,113 @@
|
||||
#!/usr/bin/env python3
|
||||
"""check_isa.py —— 校验反汇编清单里没有这颗 CPU 未实现的指令。
|
||||
|
||||
用法: python tools/check_isa.py <objdump输出.txt>
|
||||
|
||||
为什么需要它：本 CPU（srcs/rtl/cpu21_riscv_decoder.v）只实现了 RV32I 的一个
|
||||
子集，最容易踩的三个坑是：
|
||||
* 没有 auipc -> 编译器一旦生成它，整段代码就废了（多为 PIC/rodata 引起）
|
||||
* 没有 lb/lh/lbu/lhu -> 只要碰 char/short 类型的读就会出现
|
||||
* 没有有符号 div/rem（只有 divu/remu） -> 有符号除法/取余会被静默算错
|
||||
|
||||
所以这里用"白名单"方式检查：出现名单外的助记符就报错并给出修复提示。
|
||||
退出码 = 违规条数（>255 时截断），0 表示通过。
|
||||
"""
|
||||
|
||||
import sys
|
||||
|
||||
# 这颗 CPU 真正实现了的指令（见 cpu21_riscv_decoder.v）
|
||||
ALLOWED = {
|
||||
# R 型
|
||||
"add", "sub", "sll", "slt", "sltu", "xor", "srl", "sra", "or", "and",
|
||||
# M 扩展（只有这几个）
|
||||
"mul", "mulh", "mulhsu", "mulhu", "divu", "remu",
|
||||
# I 型
|
||||
"addi", "slti", "sltiu", "xori", "ori", "andi", "slli", "srli", "srai",
|
||||
# 访存：只有 lw / sw / sb（没有 lb/lh/lbu/lhu/sh）
|
||||
"lw", "sw", "sb",
|
||||
# 控制流
|
||||
"beq", "bne", "blt", "bge", "bltu", "bgeu", "jal", "jalr",
|
||||
# 高位立即数
|
||||
"lui",
|
||||
# 系统
|
||||
"ecall", "uret", "csrrw", "csrrsi", "csrrci",
|
||||
}
|
||||
|
||||
# objdump 有时仍打印伪指令；这些展开后都是上面支持的指令
|
||||
ALIAS_OK = {
|
||||
"nop", "mv", "li", "j", "jr", "ret", "neg", "not",
|
||||
"beqz", "bnez", "blez", "bgez", "bltz", "bgtz",
|
||||
"seqz", "snez", "sltz", "sgtz",
|
||||
}
|
||||
|
||||
# 违规时给出针对性提示
|
||||
HINTS = {
|
||||
"auipc": "出现了 auipc：说明编译带了 PIC/PIE 或访问了只读数据。"
|
||||
"请用 -fno-pic -mcmodel=medlow，并去掉字符串/常量表（.rodata）",
|
||||
"lb": "没有 lb：不要用 char/short 类型读内存，改用 32 位字",
|
||||
"lh": "没有 lh：同上",
|
||||
"lbu": "没有 lbu：不要用 unsigned char/short 类型读内存（写显存可以用 sb，但别读回来）",
|
||||
"lhu": "没有 lhu：同上",
|
||||
"sh": "没有 sh：只用 sw / sb",
|
||||
"div": "没有有符号 div：改用 unsigned 运算（unsigned 除法会编成 divu）",
|
||||
"rem": "没有有符号 rem：改用 unsigned 运算（unsigned 取余会编成 remu）",
|
||||
"divw": "不支持 64 位运算",
|
||||
"remw": "不支持 64 位运算",
|
||||
"call": "call 会展开成 auipc+jalr：请直接用普通函数调用（jal）",
|
||||
"tail": "tail 会展开成 auipc：请用普通跳转",
|
||||
"fence": "没有 fence/fence.i",
|
||||
"ebreak": "没有 ebreak",
|
||||
"mret": "这颗核的中断返回是 uret，不是 mret",
|
||||
"sret": "这颗核的中断返回是 uret",
|
||||
"wfi": "没有 wfi：主循环只能用轮询",
|
||||
"unimp": "出现了 unimp（非法指令/内联汇编占位）",
|
||||
}
|
||||
|
||||
|
||||
def main():
|
||||
if len(sys.argv) < 2:
|
||||
print("用法: python tools/check_isa.py <objdump输出.txt>")
|
||||
return 2
|
||||
|
||||
path = sys.argv[1]
|
||||
total = 0
|
||||
violations = []
|
||||
|
||||
with open(path, encoding="utf-8", errors="replace") as f:
|
||||
for line in f:
|
||||
if "\t" not in line:
|
||||
continue
|
||||
parts = line.split("\t")
|
||||
if len(parts) < 3 or not parts[0].strip().endswith(":"):
|
||||
continue
|
||||
mnemonic = parts[2].strip().split()[0]
|
||||
if not mnemonic:
|
||||
continue
|
||||
total += 1
|
||||
if (mnemonic not in ALLOWED) and (mnemonic not in ALIAS_OK):
|
||||
violations.append((parts[0].strip(), mnemonic, line.rstrip()))
|
||||
|
||||
print("检查了 %d 条指令。" % total)
|
||||
|
||||
if not violations:
|
||||
print("ISA 检查通过：全部指令都在本 CPU 的实现范围内。")
|
||||
return 0
|
||||
|
||||
print("")
|
||||
print("!! ISA 检查失败：有 %d 条指令这颗 CPU 没有实现：" % len(violations))
|
||||
seen = set()
|
||||
for addr, mnemonic, raw in violations[:40]:
|
||||
print(" %s %s" % (addr, raw.strip()))
|
||||
seen.add(mnemonic)
|
||||
if len(violations) > 40:
|
||||
print(" ...（只列出前 40 条）")
|
||||
|
||||
print("")
|
||||
print("修复提示：")
|
||||
for m in sorted(seen):
|
||||
print(" * %s: %s" % (m, HINTS.get(m, "不在本 CPU 的指令白名单里")))
|
||||
return min(len(violations), 255)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in New Issue
Block a user