Anccend/risc-v-cpu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
## 背景

在原有五级流水 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:
Alpha
2026-09-16 20:11:00 +08:00
commit f50639e90f
66 changed files with 19733 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pipelined-cpu/srcs/tb/tb_no_intr.v
+268
View File
@@ -0,0 +1,268 @@
// 仿真顶层：tb_no_intr —— 与 tb_cpu21_riscv_redirect_int_bpb.v 相同的测试框架，
// 但不注入任何中断脉冲，因此主程序可以不受打扰地连续运行。
//
// 与 RTL 文件（rtl/cpu21_*.v）一起编译，仿真相关文件都在 testbench/ 下。
// 示例：
// iverilog -g2012 -o cpu21_sim rtl/*.v testbench/tb_no_intr.v
// vvp cpu21_sim
// 仿真会写出 tb_no_intr.vcd，可供 GTKWave 查看。
//
// 程序镜像通过 $readmemh 从 ROM_FILE 载入 ROM 模型。$readmemh 找不到文件时
// 只会打印警告并保持内存原样，所以路径写错会让 ROM 看起来全是 NOP
// （0x00000013）。仿真器的工作目录并不固定（Vivado xsim 在
// <proj>.sim/sim_1/behav/xsim 下运行），因此本测试平台会依次探测若干候选
// 路径（testbench/rom/、../testbench/rom/、…，相对仓库根目录），并报告实际
// 命中的那个。显式给出的路径始终优先：
// vvp cpu21_sim +ROM_FILE=<path> (iverilog/vvp)
// xelab ... -generic_top "ROM_FILE=<path>" (Vivado xsim)
// 注意：PowerShell 会把命令行参数里的 "=" 拆开（xelab/xsim 报
// "Expected a switch but found …"），此时直接改本文件的 ROM_FILE 参数即可；
// ROM 镜像都在 testbench/rom/ 下，路径请用正斜杠（Verilog 字符串里 "\" 是转义符）。
module tb_no_intr #(
parameter ROM_FILE = "risc-v-benchmark_ccab.hex"
// risc-v-benchmark_ccab.hex
// cpu21_riscv_redirect_int_bpb_rom.hex
// risc-v-branch-predict.hex
);
localparam integer ROM_WORDS = 1024;
localparam integer RAM_WORDS = 1024;
localparam integer PATH_LEN = 512;
// 哨兵值：不可能出现在 RISC-V 镜像的第一个字中。
localparam [31:0] EMPTY_ROM_WORD = 32'hFFFF_FFFF;
// 中断入口地址：DUT 例化与下面的打印条件共用。DUT 用 PC[11:2] 访问 ROM，
// 因此这三个入口位于程序镜像的第 43 / 120 / 192 个字（即每个中断处理
// 程序开头的第一条 "sw ..., 0(sp)"）。
localparam [31:0] IRQ1_VECTOR = 32'h0000_30ac;
localparam [31:0] IRQ2_VECTOR = 32'h0000_31e0;
localparam [31:0] IRQ3_VECTOR = 32'h0000_3300;
reg clk;
reg reset;
reg [ 31:0] instr_i;
reg [ 31:0] data_rdata_i;
reg [ 2:0] irq_i;
reg go_i;
reg [ 31:0] rom [0:ROM_WORDS-1];
reg [ 31:0] ram [0:RAM_WORDS-1];
wire [ 31:0] instr_addr_o;
wire [ 31:0] data_addr_o;
wire [ 31:0] data_wdata_o;
wire [ 3:0] data_wstrb_o;
wire data_we_o;
wire [ 31:0] led_data_o;
wire led_valid_o;
wire [ 31:0] if_pc_o;
wire [ 31:0] id_pc_o;
wire [ 31:0] ex_pc_o;
wire [ 31:0] mem_pc_o;
wire [ 31:0] wb_pc_o;
wire [ 31:0] if_ir_o;
wire [ 31:0] id_ir_o;
wire [ 31:0] ex_ir_o;
wire [ 31:0] mem_ir_o;
wire [ 31:0] wb_ir_o;
wire [ 31:0] rdin_o;
wire [ 31:0] mdin_o;
wire reg_write_o;
wire mem_write_o;
wire halted_o;
wire [ 2:0] irq_pending_o;
wire [ 1:0] irq_current_level_o;
wire [ 31:0] uepc_o;
wire [ 31:0] ustatus_o;
wire bpb_predict_hit_o;
wire bpb_predict_taken_o;
wire bpb_mispredict_o;
wire [ 15:0] cycle_count_o;
wire [ 15:0] stall_count_o;
wire [ 15:0] bubble_count_o;
wire [ 15:0] conditional_taken_count_o;
wire [ 15:0] unconditional_branch_count_o;
wire [ 15:0] prediction_success_count_o;
wire [ 15:0] prediction_failure_count_o;
integer i;
integer tb_cycle;
reg rom_loaded;
reg [8*PATH_LEN-1:0] rom_file_path;
cpu21_riscv_redirect_int_bpb #(
.RESET_PC (32'h0000_0000),
.IRQ1_VECTOR(IRQ1_VECTOR),
.IRQ2_VECTOR(IRQ2_VECTOR),
.IRQ3_VECTOR(IRQ3_VECTOR),
// 与中断测试平台一致，复位后即使能 MIE。本测试平台从不产生 irq_i
// 脉冲，因此该参数只有在你自行添加脉冲时才有影响。
.USTATUS_INIT(32'h0000_0001)
) dut (
.clk (clk),
.reset (reset),
.instr_i (instr_i),
.data_rdata_i (data_rdata_i),
.irq_i (irq_i),
.go_i (go_i),
.instr_addr_o (instr_addr_o),
.data_addr_o (data_addr_o),
.data_wdata_o (data_wdata_o),
.data_wstrb_o (data_wstrb_o),
.data_we_o (data_we_o),
.led_data_o (led_data_o),
.led_valid_o (led_valid_o),
.if_pc_o (if_pc_o),
.id_pc_o (id_pc_o),
.ex_pc_o (ex_pc_o),
.mem_pc_o (mem_pc_o),
.wb_pc_o (wb_pc_o),
.if_ir_o (if_ir_o),
.id_ir_o (id_ir_o),
.ex_ir_o (ex_ir_o),
.mem_ir_o (mem_ir_o),
.wb_ir_o (wb_ir_o),
.rdin_o (rdin_o),
.mdin_o (mdin_o),
.reg_write_o (reg_write_o),
.mem_write_o (mem_write_o),
.halted_o (halted_o),
.irq_pending_o (irq_pending_o),
.irq_current_level_o (irq_current_level_o),
.uepc_o (uepc_o),
.ustatus_o (ustatus_o),
.bpb_predict_hit_o (bpb_predict_hit_o),
.bpb_predict_taken_o (bpb_predict_taken_o),
.bpb_mispredict_o (bpb_mispredict_o),
.cycle_count_o (cycle_count_o),
.stall_count_o (stall_count_o),
.bubble_count_o (bubble_count_o),
.conditional_taken_count_o (conditional_taken_count_o),
.unconditional_branch_count_o(unconditional_branch_count_o),
.prediction_success_count_o (prediction_success_count_o),
.prediction_failure_count_o (prediction_failure_count_o)
);
always #5 clk = ~clk;
// Logisim 的 ROM 以 PC[11:2] 作为字地址；这也让原来的三个中断向量映射到
// 相同的 ROM 表项。
always @* begin
instr_i = 32'h00000013;
if (instr_addr_o[11:2] < ROM_WORDS) instr_i = rom[instr_addr_o[11:2]];
end
// 数据存储器的异步读模型。
always @* begin
data_rdata_i = 32'b0;
if (data_addr_o[11:2] < RAM_WORDS) data_rdata_i = ram[data_addr_o[11:2]];
end
// 带字节使能的同步写模型。MMIO 区域（LED_ADDR=0x1000 起）不在本模型的
// 译码范围（data_addr_o[11:2] < 1024）内，因此对 LED 的存储不会写进 RAM。
always @(posedge clk) begin
if (!reset && data_we_o && (data_addr_o[11:2] < RAM_WORDS)) begin
if (data_wstrb_o[0]) ram[data_addr_o[11:2]][7:0] <= data_wdata_o[7:0];
if (data_wstrb_o[1]) ram[data_addr_o[11:2]][15:8] <= data_wdata_o[15:8];
if (data_wstrb_o[2]) ram[data_addr_o[11:2]][23:16] <= data_wdata_o[23:16];
if (data_wstrb_o[3]) ram[data_addr_o[11:2]][31:24] <= data_wdata_o[31:24];
end
end
always @(posedge clk) begin
if (reset) begin
tb_cycle = 0;
end else begin
tb_cycle = tb_cycle + 1;
if ((tb_cycle <= 20) || data_we_o || led_valid_o ||
(irq_pending_o != 3'b000) ||
(instr_addr_o == IRQ1_VECTOR) ||
(instr_addr_o == IRQ2_VECTOR) ||
(instr_addr_o == IRQ3_VECTOR)) begin
$display(
"t=%0t cyc=%0d PC=%08h ID=%08h EX=%08h MEM=%08h WB=%08h irq=%b pend=%b uepc=%08h LEDv=%b LED=%08h memwe=%b addr=%08h wdata=%08h wstrb=%b",
$time, tb_cycle, if_pc_o, id_ir_o, ex_ir_o, mem_ir_o, wb_ir_o, irq_i, irq_pending_o,
uepc_o, led_valid_o, led_data_o, data_we_o, data_addr_o, data_wdata_o, data_wstrb_o);
end
end
end
// 尝试从 "fname" 载入 ROM 镜像。"loaded" 为 1 表示文件存在且至少包含一个
// 字。利用 rom[0] 中的哨兵值，可以避免载入失败被静默忽略。
task load_rom_image;
input [8*PATH_LEN-1:0] fname;
output loaded;
integer fh;
begin
loaded = 1'b0;
fh = $fopen(fname, "r");
if (fh != 0) begin
$fclose(fh);
rom[0] = EMPTY_ROM_WORD;
$readmemh(fname, rom);
if (rom[0] === EMPTY_ROM_WORD) begin
// 文件能打开但内容为空：恢复默认的 NOP 填充。
rom[0] = 32'h0000_0013;
end else begin
rom_file_path = fname;
loaded = 1'b1;
$display("NOTE: ROM image loaded from \"%0s\".", fname);
end
end
end
endtask
initial begin
clk = 1'b0;
reset = 1'b1;
irq_i = 3'b000;
go_i = 1'b0;
tb_cycle = 0;
for (i = 0; i < ROM_WORDS; i = i + 1) rom[i] = 32'h00000013;
for (i = 0; i < RAM_WORDS; i = i + 1) ram[i] = 32'b0;
// 预置几个字，便于在波形中观察数据存储器的活动。
ram[1] = 32'h1234_5678;
ram[2] = 32'h89ab_cdef;
// 依次探测 ROM 镜像的常见位置，第一个可读的候选文件生效；下面的探测
// 失败是无害的（在找到真正的镜像之前，ROM 保持 0x00000013 填充）。
$display("NOTE: searching for ROM image \"%0s\" ...", ROM_FILE);
rom_loaded = 1'b0;
if ($value$plusargs("ROM_FILE=%s", rom_file_path)) load_rom_image(rom_file_path, rom_loaded);
if (!rom_loaded) load_rom_image(ROM_FILE, rom_loaded);
if (!rom_loaded) load_rom_image({"testbench/rom/", ROM_FILE}, rom_loaded);
if (!rom_loaded) load_rom_image({"../testbench/rom/", ROM_FILE}, rom_loaded);
if (!rom_loaded) load_rom_image({"../../../testbench/rom/", ROM_FILE}, rom_loaded);
if (!rom_loaded) load_rom_image({"../../../../../testbench/rom/", ROM_FILE}, rom_loaded);
// 分享出去的 Vivado 工程里的镜像目录（工程目录/srcs/rom/），GUI 仿真的工作
// 目录是 <proj>.sim/sim_1/behav/xsim，所以需要向上 5 层。
if (!rom_loaded) load_rom_image({"srcs/rom/", ROM_FILE}, rom_loaded);
if (!rom_loaded) load_rom_image({"../srcs/rom/", ROM_FILE}, rom_loaded);
if (!rom_loaded) load_rom_image({"../../../../../srcs/rom/", ROM_FILE}, rom_loaded);
if (!rom_loaded)
$display(
"WARNING: no ROM image found for \"%0s\" - the ROM stays filled with NOPs (0x00000013).",
ROM_FILE
);
$dumpfile("tb_no_intr.vcd");
$dumpvars(0, tb_no_intr);
#22 reset = 1'b0;
// 本测试平台不注入中断脉冲：irq_i 始终为 3'b000，因此只走主程序
//（非中断）执行路径。
repeat (5560) @(negedge clk);
$display(
"FINAL: tb_cycles=%0d dut_cycles=%0d stalls=%0d bubbles=%0d cond_taken=%0d uncond=%0d pred_ok=%0d pred_fail=%0d halted=%b",
tb_cycle, cycle_count_o, stall_count_o, bubble_count_o, conditional_taken_count_o,
unconditional_branch_count_o, prediction_success_count_o, prediction_failure_count_o,
halted_o);
$finish;
end
endmodule