Alpha
f50639e90f
## 背景
在原有五级流水 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 宏做行为仿真
109 lines
4.6 KiB
C
109 lines
4.6 KiB
C
/* -----------------------------------------------------------------------------
|
||
* mmio.h —— 扫雷程序的全部 MMIO 地址与编码定义（**只改这一个文件就能换地址**）
|
||
*
|
||
* 约定：本文件里的所有地址都是"数据空间"的字节地址，和 CPU 的 data_addr_o 一致。
|
||
* 写用 *(volatile unsigned *)addr（sw 全字写）或 *(volatile unsigned char *)addr
|
||
* （sb 字节写，显存必须用这个）。
|
||
*
|
||
* -----------------------------------------------------------------------------
|
||
* 地址表（与 pipelined-cpu/srcs/rtl/cpu21_mmio.v 里的译码完全一致）：
|
||
*
|
||
* 0x0000_0000 - 0x0000_0FFF 数据 RAM（4 KB，栈 + 全局变量）
|
||
* 0x0000_1000 LED 数据寄存器（低 16 位点亮 LED）
|
||
* 0x0000_1004 七段数码管：8 位十六进制（低 4 位 = 最右）
|
||
* 0x0000_1100 + 0x00 STATUS [0] 事件FIFO非空 [5:1] 项数 [6] 中断使能 [7] 满
|
||
* 0x0000_1100 + 0x04 DATA [7:0] dx [15:8] dy [20:16] 按键（读无副作用）
|
||
* 0x0000_1100 + 0x08 ACK 写任意值 -> 弹出一次事件
|
||
* 0x0000_1100 + 0x0C CTRL [0] 鼠标中断使能
|
||
* 0x0000_1100 + 0x10 INPUT [15:0] 拨码开关 [20:16] 按键
|
||
* 0x0000_1100 + 0x14 TIME 自由计数器（随机种子）
|
||
* 0x0000_1100 + 0x18 FRAME VGA 帧计数（闪烁用）
|
||
* 0x0000_1100 + 0x1C EVENTCNT 累计事件数
|
||
* 0x0000_1100 + 0x20 LEVEL 写 1 -> 触发"关卡入口"软件中断（IRQ2）
|
||
* 0x0000_1100 + 0x24 MAGIC 0xCAFE0002（自检：读得到说明 MMIO 活着）
|
||
* 0x0000_1140 + 0x00 DISP_CTRL [0] 光标可见 [6:4] 背景色
|
||
* 0x0000_1140 + 0x04 DISP_CURSOR [5:0] 列 [13:8] 行
|
||
* 0x0000_1140 + 0x08 DISP_MAGIC 0xCAFE0001
|
||
* 0x0000_2000 - 0x0000_27FF 显存：40 列 x 30 行，每格 1 字节，共 1200 字节
|
||
*
|
||
* 鼠标事件单位：1/8 格（按键一次 = 8 = 移动一格；PS/2 鼠标用原始计数）。
|
||
* 左键点击 -> 事件的 btn 位 0 置 1；右键（PS/2）-> 位 1。
|
||
*
|
||
* ⚠ 如果你的外设地址和上表不同：只改下面这几个宏，.c 文件不用动。
|
||
* ⚠ 三个中断入口必须与 linker.ld 里 .text.isr1/2/3 的地址一致：
|
||
* IRQ1(0x100) = 关卡（游戏）入口，IRQ2(0x200) = 鼠标读取，IRQ3(0x300) = 备用。
|
||
* 顶层 cpu21_board_top 的 IRQ1/2/3_VECTOR 参数也要跟着改（默认就是这个布局）。
|
||
* ---------------------------------------------------------------------------*/
|
||
#ifndef SAOLEI_MMIO_H
|
||
#define SAOLEI_MMIO_H
|
||
|
||
/* ---- LED / 七段数码管 ---- */
|
||
#define LED_ADDR 0x00001000u
|
||
#define REG_SEG 0x00001004u
|
||
|
||
/* ---- 显存 ---- */
|
||
#define FB_BASE 0x00002000u /* 显存起始（字节地址） */
|
||
#define FB_PITCH 40u /* 每行 40 格 */
|
||
#define FB_ROWS 30u /* 30 行 */
|
||
#define GRID_COLS 40u
|
||
#define GRID_ROWS 30u
|
||
|
||
/* ---- 鼠标寄存器组 ---- */
|
||
#define REG_STATUS 0x00001100u
|
||
#define REG_MDATA 0x00001104u
|
||
#define REG_MACK 0x00001108u
|
||
#define REG_MCTRL 0x0000110Cu
|
||
#define REG_INPUT 0x00001110u
|
||
#define REG_TIME 0x00001114u
|
||
#define REG_FRAME 0x00001118u
|
||
#define REG_EVCNT 0x0000111Cu
|
||
#define REG_LEVEL 0x00001120u
|
||
#define REG_MMAGIC 0x00001124u
|
||
|
||
/* ---- 显示控制器寄存器 ---- */
|
||
#define REG_CTRL 0x00001140u
|
||
#define REG_CURSOR 0x00001144u
|
||
#define REG_DMAGIC 0x00001148u
|
||
|
||
/* ---- 访问宏 ---- */
|
||
#define REG_R(a) (*(volatile unsigned *)((unsigned)(a)))
|
||
#define REG_W(a) (*(volatile unsigned *)((unsigned)(a)))
|
||
|
||
/* 显存按字节写（只能 sb，不能 lb —— 这颗核没有 lb/lbu） */
|
||
static inline void fb_write(unsigned idx, unsigned val)
|
||
{
|
||
*(volatile unsigned char *)(FB_BASE + idx) = (unsigned char)(val & 0xFFu);
|
||
}
|
||
|
||
/* ---- 格子编码：1 字节 = [3:0] 字形 [6:4] 颜色 [7] 保留 ---- */
|
||
#define G_BLANK 0u /* 空 */
|
||
#define G_N1 1u /* 数字 1..8 = 1..8 */
|
||
#define G_COVER 9u /* 未揭开 */
|
||
#define G_FLAG 10u /* 旗 */
|
||
#define G_MINE 11u /* 雷 */
|
||
#define G_BOOM 12u /* 爆炸 */
|
||
#define G_QUEST 13u /* 问号 */
|
||
#define G_BAR 14u /* 横线 */
|
||
#define G_SOLID 15u /* 实心 */
|
||
|
||
#define C_BLACK 0u
|
||
#define C_BLUE 1u
|
||
#define C_GREEN 2u
|
||
#define C_CYAN 3u
|
||
#define C_RED 4u
|
||
#define C_MAGENTA 5u
|
||
#define C_YELLOW 6u
|
||
#define C_GRAY 7u
|
||
|
||
#define CELL(g, c) ((unsigned)((g) | ((c) << 4)))
|
||
|
||
/* ---- 软件事件环形队列：中断服务程序（isr.c）生产，主循环（saolei.c）消费 ---- */
|
||
#define EVQ_SIZE 64u
|
||
#define EVQ_MASK (EVQ_SIZE - 1u)
|
||
extern volatile unsigned g_evq[EVQ_SIZE];
|
||
extern volatile unsigned g_evq_head; /* 主循环消费 */
|
||
extern volatile unsigned g_evq_tail; /* 中断生产 */
|
||
extern volatile unsigned g_evq_lost; /* 队列满丢弃计数（调试用） */
|
||
|
||
#endif /* SAOLEI_MMIO_H */
|