docs(readme): 记录上板实测出来的 PS/2 方向约定（鼠标 dy 取负）

上板已经确认：不定负号的表现就是“左右正常、上下反向”，不是解码错；另外把“键鼠静止时一个字节都不发”写成显式提醒，避免再被误判成硬件坏。
fix(ps2): 鼠标 dy 方向取负（PS/2 正 dy = 上，软件正 dy = 下）；键盘补 W/A/S/D 别名
2026-09-23 22:50:29 +08:00 · 2026-09-23 22:50:19 +08:00 · 2026-09-23 22:35:50 +08:00 · 2026-09-23 22:03:50 +08:00 · 2026-09-23 21:50:18 +08:00 · 2026-09-23 21:21:32 +08:00
18 changed files with 2155 additions and 1350 deletions
@@ -13,20 +13,20 @@ risc-v/
 ├─ README.md                             本文档
 ├─ pipelined-cpu/                        Vivado 工程目录（也是源文件所在地）
 │  ├─ create_project.tcl                 一键重建工程的 Tcl 脚本
-│  ├─ srcs/rtl/*.v                       处理器与外设 RTL（17 个文件，cpu21_riscv_redirect_int_bpb.v 为处理器顶层）
+│  ├─ srcs/rtl/*.v                       处理器与外设 RTL（18 个文件，cpu21_riscv_redirect_int_bpb.v 为处理器顶层）
 │  │                                     外设：cpu21_mmio.v（MMIO 中枢）、cpu21_vga.v（显示）、
 │  │                                     cpu21_seg7.v（数码管）、cpu21_pointer.v（按键当鼠标）、
-│  │                                     cpu21_ps2_mouse.v（可选 PS/2 鼠标）
+│  │                                     cpu21_ps2_mouse.v / cpu21_ps2_kbd.v（PS/2 鼠标、键盘接收）
 │  ├─ srcs/board/*.v|*.vh                板级顶层（时钟分频 + 片内 ROM/RAM + 引脚）；四份 ROM 初始化：
 │  │                                     cpu21_board_rom.vh / _fast.vh（跑马灯）、risc-v-intrupt-ccab.vh
 │  │                                     （课程中断综合测试程序）、cpu21_saolei_rom.vh（扫雷）
 │  ├─ srcs/constrs/*.xdc                 引脚与分频时钟约束（+ Nexys4DDR 母版）
-│  ├─ srcs/tb/*.v                        三个测试平台
+│  ├─ srcs/tb/*.v                        七个测试平台（含 PS/2 鼠标/键盘的单独自测 tb_ps2_mouse.v / tb_ps2_kbd.v）
 │  ├─ srcs/rom/*.hex                     测试平台加载的 ROM 镜像
 │  ├─ tools/                             rv_asm.py（迷你汇编器）、hex2vh.py（hex → ROM 初始化）、
 │  │                                     adapt_intrupt_ccab.py（课程中断程序 → 上板 ROM）、
 │  │                                     run_regress.ps1（一键回归）、check_rtl_text.ps1（RTL 文本体检）、
-│  │                                     rars_f0c874c.jar（课程提供的 RARS 汇编器）
+│  │                                     rars_f0c874c.jar（课程提供的 RARS 汇编器）、play_saolei.tcl（命令行玩扫雷）
 │  └─ programs/                          汇编源程序与期望值：跑马灯 demo、指令集/MMIO 测试、课程原始
 │                                        资产（risc-v-benchmark_ccab、真值表），以及中断综合测试程序
 │                                        risc-v-intrupt-ccab.asm / .hex
@@ -97,7 +97,7 @@ risc-v/
 | `0x0000_1004`             | 七段数码管     | `sw`/`sb` 写 8 位十六进制数（低 4 位 = 最右边那个数码管）                        | `lw` 读回                  |
 | `0x0000_1100`+            | 鼠标寄存器组   | STATUS / DATA / ACK / CTRL / INPUT / TIME / FRAME / EVCNT / LEVEL / MAGIC            | 同左（DATA 读无副作用）      |
 | `0x0000_1140`+            | 显示控制器     | CTRL（光标可见、背景色）/ CURSOR（列、行）                                           | 同左（另含 MAGIC 自检值）    |
-| `0x0000_2000`–`0x27FF` | 显存           | 40 列 × 30 行、每格 1 字节（字形 + 颜色），写端口接到板级顶层的双口 RAM             | `lw` 组合读回              |
+| `0x0000_2000`–`0x2FFF` | 显存           | 40 列 × 30 行、每格 2 字节（低字节 = 字形[5:0]、高字节 = 颜色[2:0]，共 2400 字节），写端口接到板级顶层的双口 RAM | `lw` 组合读回              |
 其中 `LEVEL`（`0x1120`）是一个**软件中断**寄存器：写 1 会拉起 `irq_i[1]`，用来让程序
 "跳到关卡入口"；`MAGIC`（`0xCAFE0001`/`0xCAFE0002`）可以读来自检 MMIO 是否活着。
@@ -165,14 +165,19 @@ risc-v/
 | `pipelined-cpu/srcs/rtl/cpu21_vga.v`                      | `cpu21_vga`                       | 640x480@60 显示控制器：按"格子"扫描，8x8 字模放大 2 倍填满 16x16 的格子                  |
 | `pipelined-cpu/srcs/rtl/cpu21_seg7.v`                     | `cpu21_seg7`                      | 板载 8 位数码管动态扫描驱动（共阳极，位选/段选低有效）                                   |
 | `pipelined-cpu/srcs/rtl/cpu21_pointer.v`                  | `cpu21_pointer`                   | 把 5 向按键变成"鼠标"事件（去抖 + 事件排队，单位 1/8 格）                                |
-| `pipelined-cpu/srcs/rtl/cpu21_ps2_mouse.v`                | `cpu21_ps2_mouse`                 | 可选的真鼠标：PS/2 接收（11 位帧 + 奇校验 + 3 字节包解析），只实现接收                   |
+| `pipelined-cpu/srcs/rtl/cpu21_ps2_mouse.v`                | `cpu21_ps2_mouse`                 | 可选的真鼠标：PS/2 接收（11 位帧按位下标对齐 + **奇校验** + 3 字节包解析），只实现接收      |
-| `pipelined-cpu/srcs/board/cpu21_board_top.v`              | `cpu21_board_top`                 | 板级顶层：时钟分频、复位同步、片内 ROM/RAM、显存双口 RAM、VGA/数码管/鼠标/中断连线       |
+| `pipelined-cpu/srcs/rtl/cpu21_ps2_kbd.v`                  | `cpu21_ps2_kbd`                   | 可选的真键盘：扫描码集 2 解码（`F0` 断码 / `E0` 扩展前缀），把按键映射成与鼠标同格式的事件 |
 | `pipelined-cpu/srcs/board/cpu21_board_top.v`              | `cpu21_board_top`                 | 板级顶层：时钟分频、复位同步、片内 ROM/RAM、显存双口 RAM、VGA/数码管、PS/2 键鼠选择（SW15）、中断连线 |
 | `pipelined-cpu/srcs/board/cpu21_saolei_rom.vh`            | —                                  | 扫雷程序的 ROM 初始化（由`saolei/tools/build.ps1` 生成）                               |
 | `pipelined-cpu/srcs/constrs/cpu21_board_top.xdc`          | —                                  | Nexys4DDR 引脚约束 + 分频时钟（`create_generated_clock`）                              |
 | `pipelined-cpu/srcs/board/cpu21_board_rom.vh`             | —                                  | 片内 ROM 内容（生成文件，`rom[i] = 32'h…;`）                                          |
 | `pipelined-cpu/srcs/tb/tb_board_top.v`                    | `tb_board_top`                    | 板级顶层的 RTL 仿真（观察 LED 跑马灯与写入指示）                                         |
 | `pipelined-cpu/srcs/tb/tb_no_intr.v`                      | `tb_no_intr`                      | 无中断测试平台（指令集/MMIO 测试，默认加载 benchmark 镜像）                              |
 | `pipelined-cpu/srcs/tb/tb_cpu21_riscv_redirect_int_bpb.v` | `tb_cpu21_riscv_redirect_int_bpb` | 中断与分支预测测试平台（默认加载中断测试镜像）                                           |
 | `pipelined-cpu/srcs/tb/tb_saolei.v`                       | `tb_saolei`                       | 扫雷自动打完一局并 dump 出显存（配 `saolei/tools/fb2png.py` 渲染成 PNG）                  |
 | `pipelined-cpu/srcs/tb/tb_saolei_play.v`                  | `tb_saolei_play`                  | 命令行“边玩边截图”的测试平台（配 `tools/play_saolei.tcl`）                          |
 | `pipelined-cpu/srcs/tb/tb_ps2_mouse.v`                    | `tb_ps2_mouse`                    | PS/2 鼠标接收器自测：奇校验、3 字节包、按键位（几秒出结果）                           |
 | `pipelined-cpu/srcs/tb/tb_ps2_kbd.v`                      | `tb_ps2_kbd`                      | PS/2 键盘解码自测：方向键 / Enter / 左 Shift / 松开码不产生事件                        |
 | `pipelined-cpu/tools/rv_asm.py`                           | —                                  | 迷你汇编器：`.asm` → 机器码 hex（`.lst` 带反汇编清单）                              |
 | `pipelined-cpu/tools/hex2vh.py`                           | —                                  | hex →`pipelined-cpu/srcs/board/cpu21_board_rom.vh`（`rom[i] = 32'h…;` 初始化语句） |
@@ -249,19 +254,29 @@ risc-v/
  队列 + 优先级选择器逐个上报（每拍最多一个事件，不丢键）。事件单位是 1/8 格，
  软件端只用整数加减就能换算成格（不需要除法）。
 - **`cpu21_ps2_mouse`**：可选的真鼠标，只实现接收：`ps2_clk` 下降沿把 11 位帧
-  移位进来（起始位 + 8 数据 + 奇校验 + 停止位），校验后按 3 字节包解析出
+  **按位的下标**存进 `frame_q`（`frame_q[i]` = 第 i 位，所以字节 = `frame_q[8:1]`、
-  dx/dy/按键，产生 `ev_valid_o` 脉冲。
+  校验 = `frame_q[9]`、停止 = `frame_q[10]`），停下来后判“停止位 = 1 + 奇校验”，
  再按 3 字节包解析出 dx/dy/按键，产生 `ev_valid_o` 脉冲。这里两个细节曾经写错过，
  导致真设备的数据**全被丢掉**（上板表现为 `rx_count` 恒定 0）：
  ① 原来用整体右移 `{data, frame_q[10:1]}`，判 `frame_q[10]` 时停止位还没移进来，
  判到的是校验位，字节也整体错了一位；② 原来按**偶**校验判，而 PS/2 是**奇**校验。
 - **`cpu21_ps2_kbd`**：可选的真键盘，扫描码集 2：`0xE0` = 扩展键前缀、`0xF0` = 松开
  前缀，只有**按下**才产生事件（松开码丢弃），所以按住方向键时键盘自己的重复码正好
  变成“连续移动”。产出的事件格式与鼠标**完全一致**（↑/↓/←/→ = dy/dx ±8，
  一格；Enter/空格 = 左键；左 Shift/F/C = 右键），因此 `saolei.c`/`isr.c` 一行都不用改。
 ### 板级
- **`cpu21_board_top`**：把这些接起来并裁到 23 个引脚。内含参数化分频器
+- **`cpu21_board_top`**：把这些接起来，只引出板上真正需要的引脚。内含参数化分频器
  （`CLK_DIV` / `CLK_DIV_INTRUPT`）、复位同步器（异步置位 + 同步释放）、片内
  ROM（组合读、`nop` 填充、`ifdef` 链选程序）与 RAM（字节写使能 + 组合读、
  只响应 4 KB 以内地址，避免和 MMIO 别名）、显存双口 RAM（CPU 写口 + VGA 读口
-  同处一个时钟域，用像素使能而不是第二时钟）、数码管、VGA、鼠标源选择
+  同处一个时钟域，用像素使能而不是第二时钟）、数码管、VGA、PS/2 键鼠（同一根
-  （`USE_PS2_MOUSE`）、中断连线（SW0/1/2 分别与鼠标事件/关卡软件中断相或）、
+  PS/2 线上同时挂鼠标与键盘两个解码器，用 `hid_sel`(SW15) 选哪个生效，板载 5 向
  按键始终有效）、中断连线（SW0/1/2 分别与鼠标事件/关卡软件中断相或）、
  锁存式中断指示 LED（请求上升沿置位、对应级别的 ISR 执行 `uret` 后熄灭）和
-  `led_we` 写入指示。
+  `led_we` 写入指示；另有一个“PS/2 诊断”模式把收到的字节数/时钟活动/线电平
  摆到 LED 高位（`DEBUG_PS2_RX_LED`，见下文“PS/2 键鼠”）。
 ## 上板（Nexys4DDR + Vivado）
@@ -282,9 +297,65 @@ BPB/中断观测值）。如果直接把它设为实现顶层，这些端口会
 | `rst_n`       | C12         | 按键 CPU_RESETN（低有效） | 异步置位、与 CPU 时钟同步释放                                           |
 | `go`          | N17         | 按键 BTNC                 | 对应原电路“继续运行”（`ecall` 停机后恢复执行）                      |
 | `irq_sw[2:0]` | J15/L16/M13 | 拨码开关 SW0–SW2         | 三路中断源，拨动即触发（内部同步并锁存）                                |
-| `led[15:0]`   | H17…V11    | LED0–LED15               | `LED[2:0]` = 三路中断指示（锁存，ISR 返回后熄灭），`LED[15:3]` 熄灭 |
+| `hid_sel`     | V10         | 拨码开关 SW15            | 选 PS/2 设备：0 = 键盘（默认），1 = 鼠标（见下文“PS/2 键鼠”）      |
 | `sw_flag`     | R15         | 拨码开关 SW3             | 扫雷的插旗模式（软件读 INPUT 寄存器；自动鼠标右键同样能插旗）           |
 | `led[15:0]`   | H17…V11    | LED0–LED15               | `LED[2:0]` = 三路中断指示（锁存，ISR 返回后熄灭）；`LED[15:3]` 平时熄灭，`DEBUG_PS2_RX_LED=1` 时是 PS/2 诊断（见下文） |
 | `led_we`      | R12         | LED16_B                   | MMIO 写入指示，每写一次拉长约 0.34 s @50 MHz                            |
 ### PS/2 键鼠（板载 USB HID 口，也可改接 Pmod JA）
 Nexys4DDR 右上角那个 **USB HOST** 口不是给 FPGA 直连的 USB：板上有一颗 USB↔PS/2
 桥接芯片，它把自己当 USB 主机，把键盘/鼠标当 PS/2 设备，输出的是 PS/2 的两根线
 （官方母版标明 `ps2_clk = F4`、`ps2_data = B2`）。所以 FPGA 侧只需要一个 PS/2
 接收器，**不用写 USB 协议栈**。
 | 接线方式                              | 能不能用 | 说明                                                             |
 | ------------------------------------- | -------- | ---------------------------------------------------------------- |
 | 键鼠用**有线模式**插 USB HOST          | 最推荐   | Type-C/PS2-USB 转换都用它的有线模式                              |
 | 2.4G USB 接收器                       | 可以试   | 部分复合设备桥接芯片不转发                                       |
 | 蓝牙                                  | 不行     | 桥接芯片不支持蓝牙，键盘的蓝牙链路它根本看不见                   |
 | Pmod PS/2（JA）+ 真 PS/2 键鼠          | 保底     | 直接进 FPGA，只需把 XDC 改回 `ps2_clk = C17`、`ps2_data = D18`   |
 **键盘/鼠标不动时一个字节都不发**，所以插上不动时诊断 LED 不跳是正常的：要一边按
 键/移鼠标一边看。
 **选设备：SW15 拨下（0）= PS/2 键盘，拨上（1）= PS/2 鼠标**（默认键盘）。两个
 解码器挂在同一根线上，但只有选中的那一路事件会送给 CPU —— 不能让两路同时生效：
 键盘的扫描码会凑巧组成“合法的鼠标包”，会让光标乱跳。
 诊断 LED（`DEBUG_PS2_RX_LED = 1`，默认开）：
 | LED                | 含义                                                       |
 | ------------------ | ---------------------------------------------------------- |
 | `LED[15:6]`       | 当前选中设备**收到的字节数**低 10 位（按键时数字跳 = 通了）   |
 | `LED[5]`          | `ps2_clk` 有边沿活动（时钟在动就快速翻转）                    |
 | `LED[4]` / `LED[3]` | `ps2_data` / `ps2_clk` 当前电平（静态，判断线有没有被拉死） |
 | `LED[2:0]`       | 三路中断指示（和其它模式一样）                               |
 排查口诀：**LED[5] 在跳但字节数不动** = 桥接芯片在发数据、我们的解码没认（帧格式/
 校验不匹配，先怀疑奇偶校验）；**LED[5] 也不跳** = 桥接芯片根本没转发这个设备
 （换有线模式，或改走 Pmod JA）。
 | 操作             | 键盘                              | 鼠标       |
 | ---------------- | --------------------------------- | ---------- |
 | 移动光标         | `↑` `↓` `←` `→`              | 移动       |
 | 左键（开始/开格） | `Enter`、空格                     | 左键       |
 | 右键（插旗）     | 左键 `Shift`、`F`、`C`        | 右键       |
 按住方向键 = 连续移动（用的是键盘自己的重复码）。**C 程序一行都不用改**：键盘产出的
 事件与 `cpu21_pointer`、`cpu21_ps2_mouse` 格式完全相同（±8 = 一格），一样从 IRQ2
 进 `saolei/sw/isr.c`。不想要 PS/2 就把顶层参数 `USE_PS2_MOUSE` 设为 0（只剩板载
 5 向按键）；PS/2 接收器的帧格式/校验有专门的几秒钟自测（见下文“回归测试”）。
 两条**上板实测**出来的方向约定（都值得写进报告）：
 - **鼠标的 dy 要取负**：PS/2 的原生约定是「正 dx = 右、**正 dy = 鼠标上移**」，
  而软件里「正 dx = 列 +1、**正 dy = 行 +1（向下）**」（板载按键 BTND 就是 +8），
  所以 `cpu21_ps2_mouse.v` 在拼包时把 dy 取负、dx 不动。不定这个负号的表现就是
  **左右正常、上下反向** —— 不是解码错。
 - **键鼠静止时一个字节都不发**，所以“插上不动没反应”是正常的，必须一边按键/
  移鼠标一边看 LED。
 ### 时钟：分频比怎么选（`CLK_DIV` / `CLK_DIV_INTRUPT`）
 乘除法原本是 ALU 里的组合运算（`a*b`、`a%b`），实测关键路径约 94 ns（325 级逻辑、
@@ -546,7 +617,7 @@ CPU 时钟 6.25 MHz → 50 MHz（快 8 倍），并且乘除法不再位于关
 # 1) 生成扫雷的 ROM 镜像（改了 saolei/sw/*.c 之后必须重跑这一步）
 cd saolei
 powershell -ExecutionPolicy Bypass -File tools\build.ps1 `
-    -Prefix 'C:\Users\29653\tools\risc-v\xpack-riscv-none-elf-gcc-15.2.0-1\bin\risc-none-elf-'
+    -Prefix 'C:\Users\29653\tools\riscv\xpack-riscv-none-elf-gcc-15.2.0-1\bin\riscv-none-elf-'
 # 2) 一键建"扫雷专用"工程（先清掉旧的同名工程再重建；sources_1 和 sim_1 都固定定义 SAOLEI_ROM）
 cd ..\pipelined-cpu
@@ -564,6 +635,9 @@ cd ..\pipelined-cpu
 | BTNU / BTND / BTNL / BTNR | 光标 上 / 下 / 左 / 右                                     |
 | BTNC                      | 左键：开始界面确认 / 关卡里开格                            |
 | SW3 拨上 + BTNC           | 插旗 / 取消旗                                              |
 | SW15 = 1                  | 改用 PS/2 鼠标（默认 SW15 = 0 = PS/2 键盘，见上文“PS/2 键鼠”） |
 | 键盘 `↑↓←→` / `Enter`·空格 / 左`Shift`·`F`·`C` | 移动 / 左键 / 右键（插旗）—— 需 SW15 = 0      |
 | 鼠标 移动 / 左键 / 右键   | 移动 / 左键 / 右键（插旗）—— 需 SW15 = 1                 |
 | SW0 / SW1 / SW2           | **别动**，它们会 OR 进外部中断线，一拨就可能触发中断 |
 开始界面的光标默认停在 START 按钮上，按 BTNC 进关卡；关卡里把光标移到盘面**左上角那个黄格**
@@ -571,7 +645,8 @@ cd ..\pipelined-cpu
 ### 扫雷：没有 VGA 显示器怎么玩（命令行仿真 + 每步截图）
-显存是内存映射的（`0x2000` 起，40×30 字节，每格 1 字节 = 字形[3:0] + 颜色[6:4]），
+显存是内存映射的（`0x2000` 起，40×30 格、每格 2 字节：低字节 = 字形[5:0]、
 高字节 = 颜色[2:0]，共 2400 字节 = 600 字），
 所以仿真里可以把整屏 dump 出来，再按 `cpu21_vga.v` 的字库/调色板还原成 PNG —— 等价于给 VGA 截图。
 `tools/play_saolei.tcl` 更进一步：用 `cmd.txt` 往仿真里"喂"按键，每按一步自动存一张 PNG。
@@ -592,7 +667,7 @@ $rtl = (Get-ChildItem "$p\srcs\rtl\*.v").FullName
 到 `xsim%` 提示符后（**`source` 要带 `-encoding utf-8`**，否则 xsim 按 GBK 读脚本会乱码）：
 ```text
-source -encoding utf-8 <仓库路径>/pipelined-cpu/tools/play_saolei.tcl
+source -encoding utf-8 D:/Desktop/risc-v-cpu/pipelined-cpu/tools/play_saolei.tcl
 k c          左键点击（进关卡用这个）
 k u/d/l/r    光标 上/下/左/右（也认 w/s/a/d）
@@ -638,6 +713,27 @@ powershell -ExecutionPolicy Bypass -File tools\run_regress.ps1
 | tb_cpu21_riscv_redirect_int_bpb（中断，6003 周期） | `stalls=963 bubbles=1205 cond_taken=547 uncond=28 pred_ok=557 pred_fail=87`  |
 | 板级（快速 ROM）                                   | 跑马灯`0001 → … → 8000` 循环，每步约 2.6 µs                              |
 PS/2 接收器不在上面这个脚本里（它跟板载芯片/真设备有关，不属于纯 RTL 回归），
 但解码逻辑（帧对齐、奇校验、包解析、键位映射）值得单独盯，两个自测各几秒钟：
 ```powershell
 cd pipelined-cpu
 $p = 'D:\Desktop\risc-v-cpu\pipelined-cpu'
 # 鼠标接收器
 & 'C:\Xilinx\Vivado\2020.2\bin\xvlog.bat' "$p\srcs\rtl\cpu21_ps2_mouse.v" "$p\srcs\tb\tb_ps2_mouse.v"
 & 'C:\Xilinx\Vivado\2020.2\bin\xelab.bat' -top tb_ps2_mouse -snapshot ps2m
 & 'C:\Xilinx\Vivado\2020.2\bin\xsim.bat' ps2m -R          # 期望 ALL PASS
 # 键盘解码（把 mouse 换成 kbd）
 & 'C:\Xilinx\Vivado\2020.2\bin\xvlog.bat' "$p\srcs\rtl\cpu21_ps2_kbd.v" "$p\srcs\tb\tb_ps2_kbd.v"
 & 'C:\Xilinx\Vivado\2020.2\bin\xelab.bat' -top tb_ps2_kbd -snapshot ps2k
 & 'C:\Xilinx\Vivado\2020.2\bin\xsim.bat' ps2k -R           # 期望 ALL PASS
 ```
 两个自测都会：发几个帧 → 检查事件内容是否正确；**故意发一个校验位错的帧** →
 必须整帧丢掉（不计数、不产生事件）；键盘那个还会检查“松开码（F0 xx）不产生事件”。
 ## 工程分享（Tcl 一键重建）
 `pipelined-cpu/` 已整理成“自包含 + 可直接分享”的工程目录，设计文件都在里面，
@@ -15,6 +15,8 @@
 //   rst_n  (C12)      -> 复位按键 CPU_RESETN，低有效，经复位同步器
 //   go     (N17)      -> 按键 BTNC：ecall 停机后按下继续运行
 //   irq_sw[2:0]       -> 拨码开关 SW[2:0]：3 路中断源
 //   hid_sel  (V10)    -> 拨码开关 SW[15]：选 PS/2 设备（0 = 键盘，1 = 鼠标）
 //   sw_flag  (R15)    -> 拨码开关 SW[3]：插旗模式（软件读 INPUT 寄存器）
 //   led[15:0]         -> 板载 LED[15:0]：LED[2:0] = 三路中断指示，从该路中断
 //                         请求出现开始点亮，一直到它的 ISR 执行 uret 返回后才熄灭；
 //                         LED[15:3] 熄灭
@@ -52,8 +54,18 @@ module cpu21_board_top #(
    // 取大于 2 的值只是把实际时钟变慢，XDC 的 cpu_clk 仍按最坏情况 50 MHz 约束，
    // 所以不会掩盖时序违例（约束偏严）。
    parameter integer        CLK_DIV_INTRUPT    = 32,
-    // 鼠标事件源：0 = 板上 5 向按键（免外设，默认）；1 = PS/2 鼠标（Pmod JA）
+    // PS/2 输入（板载 USB HID 口，也可改接 Pmod JA）：0 = 关闭（只剩板上 5 向按键）；
-    parameter integer        USE_PS2_MOUSE      = 0,
+    // 1 = 开启。开启后同时例化鼠标与键盘两个解码器（它们共用同一根 PS/2 线），
    // 用 SW[15]（端口 hid_sel）选哪个生效：0 = 键盘（默认），1 = 鼠标。
    // 不能两个同时生效：键盘的扫描码会凑巧组成合法的鼠标包，让光标乱跳。
    parameter integer        USE_PS2_MOUSE      = 1,
    // 调试：1 = 用 LED 高位显示 PS/2 诊断信息：
    //   LED[15:6] = 当前选中设备收到的字节数低 10 位（按一下键/动一下鼠标就跳 = 收发都通）
    //   LED[5]    = ps2_clk 有边沿活动（时钟在动就快速翻转）
    //   LED[4]    = ps2_data 当前电平
    //   LED[3]    = ps2_clk  当前电平
    // LED[2:0] 始终是三路中断指示。
    parameter integer        DEBUG_PS2_RX_LED   = 1,
    // 5 向按键去抖的采样周期（CPU 周期数）：上板默认 50000（1 ms @50 MHz）。
    // 仿真里可以传一个小值，让"按一下"在几十微秒内就被识别。
    parameter integer        POINTER_SAMPLE_DIV = 50000
@@ -67,6 +79,7 @@ module cpu21_board_top #(
    input  wire        btnl,     // P17：光标左
    input  wire        btnr,     // M17：光标右
    input  wire        sw_flag,  // R15：SW[3]，插旗模式（软件读 INPUT 寄存器）
    input  wire        hid_sel,  // V10：SW[15]，选 PS/2 设备（0 = 键盘，1 = 鼠标）
    output wire [15:0] led,      // LED[15:0]
    output wire        led_we,   // LED16_B：MMIO 写入指示
    // 七段数码管（共阳极：位选/段选都是低有效）
@@ -160,6 +173,8 @@ module cpu21_board_top #(
  wire [31:0] data_wdata;
  wire [ 3:0] data_wstrb;
  wire        data_we;
  wire [15:0] ps2_rx_count;   // PS/2 鼠标收到的字节数（用于 LED 调试显示）
  wire [15:0] kbd_rx_count;   // PS/2 键盘收到的字节数（先声明：LED 调试段要用）
  wire [31:0] led_data;  // LED_ADDR 写入值，同时作为七段数码管显示数据
  wire        led_valid;
  // 扫雷扩展外设的连线（先声明，例化在下面）
@@ -337,7 +352,34 @@ module cpu21_board_top #(
    end
  end
-  assign led = {{13{1'b0}}, irq_led_q};
+  // ---- PS/2 输入诊断：把两根线的电平与活动情况摆到 LED 上，
  //      便于判断"板载 USB HID 芯片到底有没有在发 PS/2 数据" ----
  reg ps2_clk_s1, ps2_clk_s2, ps2_data_s1, ps2_data_s2;
  reg [7:0] ps2_edge_cnt;
  always @(posedge clk_cpu or posedge reset) begin
    if (reset) begin
      ps2_clk_s1   <= 1'b1;
      ps2_clk_s2   <= 1'b1;
      ps2_data_s1  <= 1'b1;
      ps2_data_s2  <= 1'b1;
      ps2_edge_cnt <= 8'd0;
    end else begin
      ps2_clk_s1  <= ps2_clk;
      ps2_clk_s2  <= ps2_clk_s1;
      ps2_data_s1 <= ps2_data;
      ps2_data_s2 <= ps2_data_s1;
      if (ps2_clk_s1 != ps2_clk_s2)
        ps2_edge_cnt <= ps2_edge_cnt + 8'd1;
    end
  end
  // 当前选中的 PS/2 设备收到的字节数（SW[15] 选谁就显示谁）
  wire [15:0] hid_rx_sel = hid_sel ? ps2_rx_count : kbd_rx_count;
  // LED[15:3] 平时熄灭；DEBUG_PS2_RX_LED=1 时显示 PS/2 诊断信息（含义见参数注释）
  assign led = (DEBUG_PS2_RX_LED != 0)
                   ? {hid_rx_sel[9:0], ps2_edge_cnt[0], ps2_data_s2, ps2_clk_s2, irq_led_q}
                   : {{13{1'b0}}, irq_led_q};
  reg [23:0] led_we_cnt;
@@ -417,12 +459,40 @@ module cpu21_board_top #(
      .dp_o      (dp)
  );
-  // ---- 鼠标事件源 ----
+  // ---- 鼠标事件源：板载按键 与 PS/2 鼠标**同时**有效（两路事件在顶层合并） ----
  wire ev_valid;
  wire [7:0] ev_dx, ev_dy;
  wire [4:0] ev_btn;
  wire [4:0] btn_vec = {go, btnu, btnd, btnl, btnr};  // {BTNC, BTNU, BTND, BTNL, BTNR}
  // 1) 板载按键：永远保留（BTNC 当左键、上下左右当移动、SW3 当插旗开关）
  wire       ptr_valid;
  wire [7:0] ptr_dx, ptr_dy;
  wire [4:0] ptr_btn;
  cpu21_pointer #(
      .SAMPLE_DIV(POINTER_SAMPLE_DIV)
  ) u_ptr (
      .clk       (clk_cpu),
      .reset     (reset),
      .btn_i     (btn_vec),
      .ev_valid_o(ptr_valid),
      .ev_dx_o   (ptr_dx),
      .ev_dy_o   (ptr_dy),
      .ev_btn_o  (ptr_btn)
  );
  // 2) PS/2 鼠标：板载 USB HID 口经板上芯片转成 PS/2 信号（ps2_clk/ps2_data）
  wire       ps2_valid;
  wire [7:0] ps2_dx, ps2_dy;
  wire [4:0] ps2_btn;
  // PS/2 键盘：与鼠标共用同一根 PS/2 线（板上只有一个 USB HID 口）。
  // 线上只有一个设备在说话，"是哪一个"用 SW[15] 告诉硬件（hid_sel）。
  wire        kbd_valid;
  wire [7:0]  kbd_dx, kbd_dy;
  wire [4:0]  kbd_btn;
  generate
    if (USE_PS2_MOUSE != 0) begin : g_ps2
      cpu21_ps2_mouse u_ps2 (
@@ -432,27 +502,48 @@ module cpu21_board_top #(
          .ps2_clk_oe_o (),
          .ps2_data_i   (ps2_data),
          .ps2_data_oe_o(),
-          .ev_valid_o   (ev_valid),
+          .ev_valid_o   (ps2_valid),
-          .ev_dx_o      (ev_dx),
+          .ev_dx_o      (ps2_dx),
-          .ev_dy_o      (ev_dy),
+          .ev_dy_o      (ps2_dy),
-          .ev_btn_o     (ev_btn),
+          .ev_btn_o     (ps2_btn),
-          .rx_count_o   ()
+          .rx_count_o   (ps2_rx_count)
      );
-    end else begin : g_btn
+
-      cpu21_pointer #(
+      cpu21_ps2_kbd u_kbd (
-          .SAMPLE_DIV(POINTER_SAMPLE_DIV)
+          .clk        (clk_cpu),
-      ) u_ptr (
+          .reset      (reset),
-          .clk       (clk_cpu),
+          .ps2_clk_i  (ps2_clk),
-          .reset     (reset),
+          .ps2_data_i (ps2_data),
-          .btn_i     (btn_vec),
+          .ev_valid_o (kbd_valid),
-          .ev_valid_o(ev_valid),
+          .ev_dx_o    (kbd_dx),
-          .ev_dx_o   (ev_dx),
+          .ev_dy_o    (kbd_dy),
-          .ev_dy_o   (ev_dy),
+          .ev_btn_o   (kbd_btn),
-          .ev_btn_o  (ev_btn)
+          .rx_count_o (kbd_rx_count)
      );
    end else begin : g_no_ps2
      assign ps2_valid    = 1'b0;
      assign ps2_dx       = 8'd0;
      assign ps2_dy       = 8'd0;
      assign ps2_btn      = 5'd0;
      assign ps2_rx_count = 16'd0;
      assign kbd_valid    = 1'b0;
      assign kbd_dx       = 8'd0;
      assign kbd_dy       = 8'd0;
      assign kbd_btn      = 5'd0;
      assign kbd_rx_count = 16'd0;
    end
  endgenerate
  // 3) 只放行 SW[15] 选中的那一路 PS/2 设备（另一个解码器虽然也在听，但事件被挡住）
  wire m_valid = ps2_valid &  hid_sel;   // SW[15] = 1 -> PS/2 鼠标
  wire k_valid = kbd_valid & ~hid_sel;   // SW[15] = 0 -> PS/2 键盘
  // 4) 合并：三个源相互独立，同一拍只会有一方产生事件；优先 PS/2
  assign ev_valid = m_valid | k_valid | ptr_valid;
  assign ev_dx    = m_valid ? ps2_dx  : k_valid ? kbd_dx  : ptr_dx;
  assign ev_dy    = m_valid ? ps2_dy  : k_valid ? kbd_dy  : ptr_dy;
  assign ev_btn   = m_valid ? ps2_btn : k_valid ? kbd_btn : ptr_btn;
 endmodule
 `default_nettype wire
@@ -63,6 +63,9 @@ set_property -dict { PACKAGE_PIN M17   IOSTANDARD LVCMOS33 } [get_ports { btnr }
 ## SW[3]：插旗模式（1 = 点击时插旗/取消旗）
 set_property -dict { PACKAGE_PIN R15   IOSTANDARD LVCMOS33 } [get_ports { sw_flag }]
 ## SW[15]：选 PS/2 设备（0 = 键盘，1 = 鼠标）；工程里插的是哪个就拨到哪边
 set_property -dict { PACKAGE_PIN V10   IOSTANDARD LVCMOS33 } [get_ports { hid_sel }]
 ## 七段数码管（共阳极：位选/段选都是低有效）
 set_property -dict { PACKAGE_PIN T10   IOSTANDARD LVCMOS33 } [get_ports { seg[0] }]
 set_property -dict { PACKAGE_PIN R10   IOSTANDARD LVCMOS33 } [get_ports { seg[1] }]
@@ -97,6 +100,9 @@ set_property -dict { PACKAGE_PIN D8    IOSTANDARD LVCMOS33 } [get_ports { vga_b[
 set_property -dict { PACKAGE_PIN B11   IOSTANDARD LVCMOS33 } [get_ports { vga_hs }]
 set_property -dict { PACKAGE_PIN B12   IOSTANDARD LVCMOS33 } [get_ports { vga_vs }]
-## PS/2 鼠标（可选：Pmod JA 插 Pmod PS2，顶层 USE_PS2_MOUSE=1）
+## PS/2 鼠标：接**板载 USB HID 口**（板上芯片把 USB 键鼠转成 PS/2）
-set_property -dict { PACKAGE_PIN C17   IOSTANDARD LVCMOS33 PULLUP true } [get_ports { ps2_clk }]
+##   Nexys4DDR_Master.xdc 里写明：ps2_clk = F4、ps2_data = B2
-set_property -dict { PACKAGE_PIN D18   IOSTANDARD LVCMOS33 PULLUP true } [get_ports { ps2_data }]
+##   顶层参数 USE_PS2_MOUSE=1 启用；板载按键仍然可用（两路事件在顶层合并）
 ##   若改用 Pmod JA 上的 Pmod PS2，把下面两行的引脚换成 C17 / D18 即可
 set_property -dict { PACKAGE_PIN F4    IOSTANDARD LVCMOS33 PULLUP true } [get_ports { ps2_clk }]
 set_property -dict { PACKAGE_PIN B2    IOSTANDARD LVCMOS33 PULLUP true } [get_ports { ps2_data }]
@@ -42,7 +42,7 @@
 // -----------------------------------------------------------------------------
 module cpu21_mmio #(
    parameter [31:0] LED_ADDR = 32'h0000_1000,
-    parameter integer FB_WORDS = 300,
+    parameter integer FB_WORDS = 600,   // 600 字 = 2400 字节（40x30 格，每格 2 字节）
    parameter integer FIFO_DEPTH = 16
 ) (
    input  wire        clk,
@@ -0,0 +1,151 @@
 `timescale 1ns / 1ps
 // =============================================================================
 // cpu21_ps2_kbd —— PS/2 键盘接收（扫描码集 2），把按键映射成"鼠标事件"
 //
 // 为什么映射成鼠标事件：saolei.c / isr.c 早就是按鼠标事件 {btn, dy, dx} 写的，
 // 键盘只要产出**同样格式**的事件，软件一行都不用改。
 //
 //   ↑ ↓ ← →          光标移动（dx/dy = ±8，恰好是软件里的"一格"）
 //   W A S D          同上（别名，与 tools/play_saolei.tcl 一致）
 //   Enter / 空格      左键（开格）
 //   左 Shift / F / C  右键（软件里右键 = 插旗）
 //
 //   方向约定跟软件对齐：**dy = +8 是向下**（与 cpu21_pointer 的 BTND、cpu21_ps2_mouse 一致），
 //   所以 ↑ 发 dy = 248（= -8 的补码）。
 //
 // PS/2 键盘发扫描码（集 2）：
 //   0xF0 前缀 -> 下一个码是"松开"（break）；0xE0 前缀 -> 下一个码是扩展键
 //   方向键是扩展键：↑ = E0 75、↓ = E0 72、← = E0 6B、→ = E0 74
 //   所以只对"按下"（make）产生事件。按住不动时键盘自己会发重复码，
 //   于是按住方向键正好变成"连续移动"。
 //
 // 与 cpu21_ps2_mouse 共用同一根 PS/2 线：两个接收器都挂在线上，只有插着的那个
 // 设备会产生有效数据，所以顶层把两者的事件一起 OR 起来即可，不用二选一。
 // =============================================================================
 module cpu21_ps2_kbd (
        input  wire        clk,
        input  wire        reset,
        input  wire        ps2_clk_i,
        input  wire        ps2_data_i,
        output reg         ev_valid_o,   // 单周期脉冲
        output reg  [7:0]  ev_dx_o,      // 有符号，1/8 格（±8 = 一格）
        output reg  [7:0]  ev_dy_o,
        output reg  [4:0]  ev_btn_o,     // bit0 = 左键, bit1 = 右键
        output reg  [15:0] rx_count_o    // 收到的字节数（调试观察用）
    );
    // ---- 两级同步 ----
    reg ps2_clk_s1, ps2_clk_s2, ps2_data_s1, ps2_data_s2;
    always @(posedge clk or posedge reset) begin
        if (reset) begin
            ps2_clk_s1  <= 1'b1;
            ps2_clk_s2  <= 1'b1;
            ps2_data_s1 <= 1'b1;
            ps2_data_s2 <= 1'b1;
        end
        else begin
            ps2_clk_s1  <= ps2_clk_i;
            ps2_clk_s2  <= ps2_clk_s1;
            ps2_data_s1 <= ps2_data_i;
            ps2_data_s2 <= ps2_data_s1;
        end
    end
    wire clk_fall = ~ps2_clk_s1 & ps2_clk_s2;
    reg [3:0]  bit_cnt_q;
    reg [10:0] frame_q;
    reg        brk_q;   // 刚收到 0xF0：下一个码是松开
    reg        ext_q;   // 刚收到 0xE0：下一个码是扩展键
    // 11 位里 data + parity 共 9 位，PS/2 是**奇校验**：1 的个数应为奇数
    function automatic parity_ok(input [8:0] dp);   // dp = {parity, d7..d0}
        parity_ok = ^dp;
    endfunction
    // 处理一个扫描码（按下才产生事件）
    task handle_code;
        input [7:0] sc;
        reg         pressed;
        begin
            rx_count_o <= rx_count_o + 16'd1;
            pressed    = (brk_q == 1'b0);   // 0xF0 之后的码是"松开"
            brk_q      <= 1'b0;
            if (sc == 8'hE0)
                ext_q <= 1'b1;              // 扩展前缀
            else if (sc == 8'hF0)
                brk_q <= 1'b1;              // 断码前缀
            else if (pressed) begin
                if (ext_q) begin
                    case (sc)
                        8'h75: begin ev_dx_o <= 8'd0; ev_dy_o <= 8'd248; ev_btn_o <= 5'd0; ev_valid_o <= 1'b1; end // ↑
                        8'h72: begin ev_dx_o <= 8'd0; ev_dy_o <= 8'd8; ev_btn_o <= 5'd0; ev_valid_o <= 1'b1; end // ↓
                        8'h6B: begin ev_dx_o <= 8'd248; ev_dy_o <= 8'd0; ev_btn_o <= 5'd0; ev_valid_o <= 1'b1; end // ←
                        8'h74: begin ev_dx_o <= 8'd8; ev_dy_o <= 8'd0; ev_btn_o <= 5'd0; ev_valid_o <= 1'b1; end // →
                        default: ;
                    endcase
                end
                else begin
                    case (sc)
                        8'h5A: begin ev_dx_o <= 8'd0; ev_dy_o <= 8'd0; ev_btn_o <= 5'b00001; ev_valid_o <= 1'b1; end // Enter
                        8'h29: begin ev_dx_o <= 8'd0; ev_dy_o <= 8'd0; ev_btn_o <= 5'b00001; ev_valid_o <= 1'b1; end // 空格
                        8'h12: begin ev_dx_o <= 8'd0; ev_dy_o <= 8'd0; ev_btn_o <= 5'b00010; ev_valid_o <= 1'b1; end // 左 Shift
                        8'h2B: begin ev_dx_o <= 8'd0; ev_dy_o <= 8'd0; ev_btn_o <= 5'b00010; ev_valid_o <= 1'b1; end // F
                        8'h2E: begin ev_dx_o <= 8'd0; ev_dy_o <= 8'd0; ev_btn_o <= 5'b00010; ev_valid_o <= 1'b1; end // C
                        // W/A/S/D 也当方向键（和 tools/play_saolei.tcl 里的别名保持一致）
                        8'h1D: begin ev_dx_o <= 8'd0;   ev_dy_o <= 8'd248; ev_btn_o <= 5'd0; ev_valid_o <= 1'b1; end // W = ↑
                        8'h1B: begin ev_dx_o <= 8'd0;   ev_dy_o <= 8'd8;   ev_btn_o <= 5'd0; ev_valid_o <= 1'b1; end // S = ↓
                        8'h1C: begin ev_dx_o <= 8'd248; ev_dy_o <= 8'd0;   ev_btn_o <= 5'd0; ev_valid_o <= 1'b1; end // A = ←
                        8'h23: begin ev_dx_o <= 8'd8;   ev_dy_o <= 8'd0;   ev_btn_o <= 5'd0; ev_valid_o <= 1'b1; end // D = →
                        default: ;
                    endcase
                end
            end
            // 一次前缀组合处理完，清掉扩展标志（松开码 E0 F0 xx 也走这里）
            if ((sc != 8'hE0) && (sc != 8'hF0))
                ext_q <= 1'b0;
        end
    endtask
    always @(posedge clk or posedge reset) begin
        if (reset) begin
            bit_cnt_q  <= 4'd0;
            frame_q    <= 11'd0;
            brk_q      <= 1'b0;
            ext_q      <= 1'b0;
            ev_valid_o <= 1'b0;
            ev_dx_o    <= 8'd0;
            ev_dy_o    <= 8'd0;
            ev_btn_o   <= 5'd0;
            rx_count_o <= 16'd0;
        end
        else begin
            ev_valid_o <= 1'b0;
            if (clk_fall) begin
                // frame_q[i] = 这一帧的第 i 位：0 = 起始，1..8 = 数据 d0..d7（LSB 先），
                //              9 = 校验，10 = 停止。按”位的下标“存，不要再整体右移：
                // 右移的话停止位还没进来就先去判 frame_q[10]，判到的是校验位。
                if (bit_cnt_q == 4'd0) begin
                    if (ps2_data_s2 == 1'b0)  // 起始位有效，开始收
                        bit_cnt_q <= 4'd1;
                end
                else begin
                    frame_q[bit_cnt_q] <= ps2_data_s2;
                    if (bit_cnt_q == 4'd10) begin
                        bit_cnt_q <= 4'd0;
                        // 停止位就是刚采到的这一位（frame_q[10] 本拍还没更新到），
                        // 校验位查 data + parity 的奇校验
                        if ((ps2_data_s2 == 1'b1) && parity_ok(frame_q[9:1]))
                            handle_code(frame_q[8:1]);
                    end
                    else
                        bit_cnt_q <= bit_cnt_q + 4'd1;
                end
            end
        end
    end
 endmodule
@@ -4,17 +4,23 @@
 // -----------------------------------------------------------------------------
 // cpu21_ps2_mouse —— 可选的真鼠标输入：PS/2 鼠标（Digilent Pmod PS2 插在 JA 上）。
 //
-// JA[1] = PS/2 DATA，JA[2] = PS/2 CLK（两条线都需要上拉，见 XDC 里的 PULLUP）。
+// JA[1] = PS/2 DATA，JA[2] = PS/2 CLK（两条线都需要上拉）。当前 XDC 把 ps2_clk /
 // ps2_data 接到板载 USB HID 口的 PS/2 侧（F4 / B2），也可以改回 JA（C17 / D18）。
 //
-// 注意：本模块没有在真实硬件上验证过（作者手头没有 PS/2 鼠标），如果你不用真
+// 注意：接收/解析逻辑（包括帧对齐与奇校验）已由 srcs/tb/tb_ps2_mouse.v 仿真验证；
-// 鼠标，请让顶层用 cpu21_pointer（5 向按键）作为事件源即可，C 程序完全不用改。
+// 板上那一侧能不能收到数据，取决于板载 USB→PS/2 桥接芯片是否肯转发你插的设备。
-// 板级顶层 cpu21_board_top 用参数 USE_PS2_MOUSE 选择这两者。
+// 如果你不用真鼠标，请让顶层用 cpu21_pointer（5 向按键）作为事件源即可，
 // C 程序完全不用改。板级顶层 cpu21_board_top 用参数 USE_PS2_MOUSE 选择这两者。
 //
 // 实现内容：
 //   1) 接收：在 ps2_clk 的下降沿采样 ps2_data，收满 11 位（起始 0 + 8 数据
 //      LSB 先 + 奇校验 + 停止 1）后校验并拼成 3 字节一包；
 //      frame_q[i] = 这一帧的第 i 位（0 起始、1..8 = d0..d7、9 校验、10 停止），
 //      所以字节 = frame_q[8:1]（frame_q[1] 就是 d0），校验 = frame_q[9]。
 //      注意 PS/2 是**奇校验**：data + parity 9 位里 1 的个数为奇数。
 //   2) 解析：byte0 = 标志（bit0 左键、bit1 右键、bit3 固定 1），byte1 = dx，
-//      byte2 = dy，bit7 为符号位；
+//      byte2 = dy，bit7 为符号位；dx 正 = 右，**dy 正 = 上**（PS/2 的原生方向），
 //      而软件里正 dy = 下，所以上报前把 dy 取负，让鼠标和板载按键/键盘方向一致；
 //   3) 上报：当 dx/dy 非 0 或按键状态变化时产生一个事件（单位与
 //      cpu21_pointer 相同，即原始计数 = 1/8 格）；
 //   4) 本模块只做"接收"，不实现主机→鼠标的命令发送（0xF4 使能上报）。多数
@@ -76,9 +82,9 @@ module cpu21_ps2_mouse (
    reg [7:0]  dx_q, dy_q;
    reg [4:0]  btn_q;        // {4'b0, middle, right, left} -> 只取低 3 位使用
-    // 校验：11 位中 1 的个数应为奇数（奇校验）
+    // 校验：PS/2 是**奇校验**，data 8 位 + parity 位共 9 位里 1 的个数应为奇数
-    function automatic odd_parity_ok(input [10:0] f);
+    function automatic parity_ok(input [8:0] dp);   // dp = {parity, d7..d0}
-        odd_parity_ok = ^{f[9:1]};  // data + parity 共 9 位，1 的个数应为偶数
+        parity_ok = ^dp;
    endfunction
    always @(posedge clk or posedge reset) begin
@@ -95,17 +101,20 @@ module cpu21_ps2_mouse (
            ev_valid_o <= 1'b0;
            if (clk_fall) begin
-                if (bit_cnt_q == 4'd0 && ps2_data_s2 == 1'b0) begin
+                // frame_q[i] = 这一帧的第 i 位：0 = 起始，1..8 = 数据 d0..d7（LSB 先），
-                    // 起始位有效，开始收
+                //              9 = 校验，10 = 停止。按”位的下标“存，不要再整体右移：
-                    frame_q   <= {ps2_data_s2, frame_q[10:1]};
+                // 右移的话停止位还没进来就先去判 frame_q[10]，判到的是校验位。
-                    bit_cnt_q <= 4'd1;
+                if (bit_cnt_q == 4'd0) begin
                    if (ps2_data_s2 == 1'b0)  // 起始位有效，开始收
                        bit_cnt_q <= 4'd1;
                end
-                else if (bit_cnt_q != 4'd0) begin
+                else begin
-                    frame_q <= {ps2_data_s2, frame_q[10:1]};
+                    frame_q[bit_cnt_q] <= ps2_data_s2;
                    if (bit_cnt_q == 4'd10) begin
                        bit_cnt_q <= 4'd0;
-                        // f = {停止, 校验, 8 数据, 起始}，这里只关心数据与校验
+                        // 停止位就是刚采到的这一位（frame_q[10] 本拍还没更新到），
-                        if (odd_parity_ok(frame_q) && (frame_q[10] == 1'b1)) begin
+                        // 校验查 data + parity 的奇校验
                        if ((ps2_data_s2 == 1'b1) && parity_ok(frame_q[9:1])) begin
                            rx_count_o <= rx_count_o + 16'd1;
                            case (byte_cnt_q)
                                8'd0: begin
@@ -123,8 +132,10 @@ module cpu21_ps2_mouse (
                                end
                                8'd2: begin
                                    byte_cnt_q <= 8'd0;
-                                    ev_dx_o    <= pkt_q[15:8];   // byte1 = dx
+                                    ev_dx_o    <= pkt_q[15:8];   // byte1 = dx（正 = 右，与软件一致）
-                                    ev_dy_o    <= frame_q[8:1];  // byte2 = dy
+                                    // byte2 = dy：**PS/2 的正 dy 是鼠标上移**，而软件里正 dy = 光标下移
                                    // （与 cpu21_pointer 的 BTND = +8 一致），所以这里要取负。
                                    ev_dy_o    <= 8'd0 - frame_q[8:1];
                                    // 与 cpu21_mmio / mmio.h 一致：bit0=左键, bit1=右键, bit2=中键
                                    ev_btn_o   <= {2'b0, pkt_q[2], pkt_q[1], pkt_q[0]};
                                    ev_valid_o <= 1'b1;
@@ -48,7 +48,11 @@ module cpu21_riscv_redirect_int_bpb #(
        // MMIO：LED 数据寄存器地址（默认 0x0000_1000，位于 4 KB 数据 RAM 之外）。
        parameter [31:0] LED_ADDR = 32'h0000_1000,
        // ustatus 复位值。详见 cpu21_riscv_irq_ctrl 中的说明。
-        parameter [31:0] USTATUS_INIT = 32'h0000_0001
+        parameter [31:0] USTATUS_INIT = 32'h0000_0001,
        // 显存字数：600 字 = 2400 字节 = 40x30 格、每格 2 字节（字形 + 颜色）。
        // 必须传给 cpu21_mmio：它的 fb_ok 是 (fb_widx < FB_WORDS)，不传就会
        // 把显存写卡在前 300 字（前 15 行），屏幕下半部分永远刷不出来。
        parameter integer FB_WORDS = 600
    ) (
        input wire        clk,
        input wire        reset,
@@ -69,7 +73,7 @@ module cpu21_riscv_redirect_int_bpb #(
        output wire [31:0] seg_data_o,        // 七段数码管：8 位十六进制数
        output wire        seg_valid_o,
        output wire        fb_we_o,           // 显存写端口（板级顶层的双口 RAM）
-        output wire [ 9:0] fb_waddr_o,        // 显存字地址（0..299）
+        output wire [ 9:0] fb_waddr_o,        // 显存字地址（0..599）
        output wire [31:0] fb_wdata_o,
        output wire [ 3:0] fb_wstrb_o,
        input  wire [31:0] fb_rdata_i,        // 显存读回（组合）
@@ -479,7 +483,8 @@ module cpu21_riscv_redirect_int_bpb #(
    wire        mmio_rdata_hit;
    cpu21_mmio #(
-                   .LED_ADDR(LED_ADDR)
+                   .LED_ADDR(LED_ADDR),
                   .FB_WORDS(FB_WORDS)
               ) u_mmio (
                   .clk        (clk),
                   .reset      (reset),
@@ -280,7 +280,9 @@ module cpu21_vga #(
  //   VGA 上和图里都能一眼看到指针。想改回闪动：把 blink_q 加回来，
  //   再在 cursor_box 里与上 blink 即可。
  // ---------------------------------------------------------------------------
-  wire cursor_here = (cursor_i[4:0] == ccol) && (cursor_i[12:8] == crow);
+  // 列必须比 6 位（0..39）：hard 难度的棋盘宽 30，光标能到列 35，
  // 以前这里只取 [4:0]，35 被当成 3，光标会“跳回最左边”。
  wire cursor_here = (cursor_i[5:0] == ccol) && (cursor_i[12:8] == crow);
  wire on_border = (hx[3:0] < 4'd2) || (hx[3:0] > 4'd13) || (vy[3:0] < 4'd2) || (vy[3:0] > 4'd13);
  wire cursor_box = cursor_here && ctrl_i[0] && on_border;
@@ -38,6 +38,7 @@ module tb_board_top;
                        .btnl    (1'b0),
                        .btnr    (1'b0),
                        .sw_flag (1'b0),
                        .hid_sel (1'b0),
                        .ps2_clk (1'b1),
                        .ps2_data(1'b1),
                        .an      (),
@@ -0,0 +1,169 @@
 `timescale 1ns / 1ps
 // =============================================================================
 // tb_ps2_kbd —— 单独验证 PS/2 键盘解码（扫描码集 2）
 //
 //   发 → 键（E0 74）应产生 dx=+8；发 ↑（E0 75）应产生 dy=-8；
 //   发 Enter（5A）应产生 btn=1（开格）；发 左Shift（12）应产生 btn=2（插旗）；
 //   发 W（1D）应产生 dy=-8（W/A/S/D 别名）；
 //   松开码（F0 xx）不应产生事件；校验位错的帧应被整帧丢掉。
 //
 //   PS/2 键盘发扫描码（集 2）：0xF0 前缀 = 下一个码是"松开"，0xE0 前缀 = 扩展键，
 //   方向键是扩展键（↑ = E0 75、↓ = E0 72、← = E0 6B、→ = E0 74），
 //   所以解码器只对"按下"产生事件。键盘自动重复 = 按住方向键时连续移动。
 //
 //   跑法：
 //     xvlog srcs/rtl/cpu21_ps2_kbd.v srcs/tb/tb_ps2_kbd.v
 //     xelab -top tb_ps2_kbd -snapshot kbdsim
 //     xsim kbdsim -R
 // =============================================================================
 module tb_ps2_kbd;
    reg clk = 1'b0;
    reg reset = 1'b1;
    reg ps2_clk = 1'b1;
    reg ps2_data = 1'b1;
    wire        ev_valid;
    wire [7:0]  ev_dx, ev_dy;
    wire [4:0]  ev_btn;
    wire [15:0] rx_count;
    always #10 clk = ~clk;                  // 50 MHz
    cpu21_ps2_kbd dut (
        .clk        (clk),
        .reset      (reset),
        .ps2_clk_i  (ps2_clk),
        .ps2_data_i (ps2_data),
        .ev_valid_o (ev_valid),
        .ev_dx_o    (ev_dx),
        .ev_dy_o    (ev_dy),
        .ev_btn_o   (ev_btn),
        .rx_count_o (rx_count)
    );
    // 发一个 PS/2 位：先摆数据，稳定后拉低时钟（DUT 在下降沿采样）
    task send_bit;
        input b;
        begin
            ps2_data = b;
            #(10_000);
            ps2_clk = 1'b0;
            #(20_000);
            ps2_clk = 1'b1;
            #(20_000);
        end
    endtask
    // 发一个字节：起始 0 + 8 位数据(LSB first) + 奇校验 + 停止 1
    task send_byte;
        input [7:0] d;
        integer i;
        reg p;
        begin
            p = ~^d;                        // 奇校验
            send_bit(1'b0);
            for (i = 0; i < 8; i = i + 1)
                send_bit(d[i]);
            send_bit(p);
            send_bit(1'b1);
        end
    endtask
    // 校验位错的字节（应被整帧丢掉）
    task send_byte_bad_parity;
        input [7:0] d;
        integer i;
        begin
            send_bit(1'b0);
            for (i = 0; i < 8; i = i + 1)
                send_bit(d[i]);
            send_bit(^d);
            send_bit(1'b1);
        end
    endtask
    integer n_ev = 0;
    integer ok = 1;
    integer exp_dx, exp_dy, exp_btn;
    always @(posedge clk) begin
        if (ev_valid) begin
            n_ev = n_ev + 1;
            $display("  [kbd] event #%0d: dx=%0d dy=%0d btn=%b", n_ev, $signed(ev_dx), $signed(ev_dy), ev_btn);
            if ((exp_dx != 999) && ($signed(ev_dx) != exp_dx)) begin
                $display("  [kbd] FAIL: 期望 dx=%0d", exp_dx);
                ok = 0;
            end
            if ((exp_dy != 999) && ($signed(ev_dy) != exp_dy)) begin
                $display("  [kbd] FAIL: 期望 dy=%0d", exp_dy);
                ok = 0;
            end
            if ((exp_btn != 999) && (ev_btn != exp_btn)) begin
                $display("  [kbd] FAIL: 期望 btn=%b", exp_btn);
                ok = 0;
            end
        end
    end
    initial begin
        $display("[kbd] === PS/2 keyboard decode test ===");
        #2000;
        reset = 1'b0;
        #2000;
        // 校验错的字节（0x74）不能被当成"→"键
        $display("[kbd] 校验位错的字节应该被丢掉");
        exp_dx = 999; exp_dy = 999; exp_btn = 999;
        send_byte_bad_parity(8'h74);
        #(100_000);
        if (n_ev != 0) begin
            $display("  [kbd] FAIL: 校验错的帧不该产生事件");
            ok = 0;
        end
        $display("[kbd] 只发松开码 F0 75（不该有事件）");
        send_byte(8'hF0);
        send_byte(8'h75);
        #(100_000);
        if (n_ev != 0) begin
            $display("  [kbd] FAIL: 松开码不该产生事件");
            ok = 0;
        end
        $display("[kbd] → 键（E0 74）期望 dx=+8");
        exp_dx = 8; exp_dy = 0; exp_btn = 0;
        send_byte(8'hE0);
        send_byte(8'h74);
        #(100_000);
        $display("[kbd] ↑ 键（E0 75）期望 dy=-8");
        exp_dx = 0; exp_dy = -8; exp_btn = 0;
        send_byte(8'hE0);
        send_byte(8'h75);
        #(100_000);
        $display("[kbd] Enter（5A）期望 btn=00001");
        exp_dx = 0; exp_dy = 0; exp_btn = 5'b00001;
        send_byte(8'h5A);
        #(100_000);
        $display("[kbd] 左 Shift（12）期望 btn=00010（软件里 = 插旗）");
        exp_dx = 0; exp_dy = 0; exp_btn = 5'b00010;
        send_byte(8'h12);
        #(100_000);
        $display("[kbd] W 键（1D）期望 dy=-8（W/A/S/D 是方向键别名）");
        exp_dx = 0; exp_dy = -8; exp_btn = 0;
        send_byte(8'h1D);
        #(100_000);
        $display("[kbd] rx_count=%0d events=%0d", rx_count, n_ev);
        if ((ok == 0) || (n_ev != 5))
            $display("[kbd] === FAIL ===");
        else
            $display("[kbd] === ALL PASS ===");
        $finish;
    end
 endmodule
@@ -0,0 +1,153 @@
 `timescale 1ns / 1ps
 // =============================================================================
 // tb_ps2_mouse —— 单独验证 PS/2 鼠标接收逻辑（不跑 CPU，几秒出结果）
 //
 //   模拟 PS/2 鼠标发 3 字节包：
 //     byte0 = 标志字节（bit3 必须为 1 才是有效的鼠标数据；bit0/1/2 = 左/右/中键）
 //     byte1 = dx（有符号）    byte2 = dy（有符号）
 //   检查 cpu21_ps2_mouse 是否给出正确的 ev_valid / ev_dx / ev_dy / ev_btn。
 //
 //   PS/2 时序：DUT 在 ps2_clk 的**下降沿**采样 ps2_data，所以这里先把数据摆好，
 //   再拉低时钟。一帧 11 位 = 起始 0 + 8 位数据(LSB 先) + **奇校验** + 停止 1。
 //   奇校验 = 校验位让 data + parity 共 9 位里 1 的个数为奇数（真设备就是这么发的）。
 //
 //   方向约定：PS/2 的 **dx 正 = 右、dy 正 = 上**（真鼠标往上推，byte2 是正数）；
 //   而软件（saolei.c / cpu21_pointer）里 **dy 正 = 向下（行号增加）**，
 //   所以 cpu21_ps2_mouse 上报前把 dy 取负 —— 本测试就是盯这个约定：
 //   发“向上”的 dy，事件里必须得到负的 dy。
 //
 //   跑法（Vivado 的 xvlog/xelab/xsim 或其它仿真器都行）：
 //     xvlog srcs/rtl/cpu21_ps2_mouse.v srcs/tb/tb_ps2_mouse.v
 //     xelab -top tb_ps2_mouse -snapshot ps2sim
 //     xsim ps2sim -R
 // =============================================================================
 module tb_ps2_mouse;
    reg clk = 1'b0;
    reg reset = 1'b1;
    reg ps2_clk = 1'b1;
    reg ps2_data = 1'b1;
    wire        ev_valid;
    wire [7:0]  ev_dx;
    wire [7:0]  ev_dy;
    wire [4:0]  ev_btn;
    wire [15:0] rx_count;
    always #10 clk = ~clk;              // 50 MHz，和板上 CPU 主频一致
    cpu21_ps2_mouse dut (
        .clk          (clk),
        .reset        (reset),
        .ps2_clk_i    (ps2_clk),
        .ps2_clk_oe_o (),
        .ps2_data_i   (ps2_data),
        .ps2_data_oe_o(),
        .ev_valid_o   (ev_valid),
        .ev_dx_o      (ev_dx),
        .ev_dy_o      (ev_dy),
        .ev_btn_o     (ev_btn),
        .rx_count_o   (rx_count)
    );
    // 发一个 PS/2 位：先摆数据，稳定后再拉低时钟（DUT 在下降沿采样）
    task send_bit;
        input b;
        begin
            ps2_data = b;
            #(10_000);
            ps2_clk = 1'b0;
            #(20_000);
            ps2_clk = 1'b1;
            #(20_000);
        end
    endtask
    // 发一个字节：起始 0 + 8 位数据(LSB first) + 奇校验 + 停止 1
    task send_byte;
        input [7:0] d;
        integer i;
        reg p;
        begin
            p = ~^d;                    // 奇校验：data + parity 里 1 的个数为奇数
            send_bit(1'b0);
            for (i = 0; i < 8; i = i + 1)
                send_bit(d[i]);
            send_bit(p);
            send_bit(1'b1);
        end
    endtask
    // 故意发一个校验位错的字节（用于确认校验真的在起作用）
    task send_byte_bad_parity;
        input [7:0] d;
        integer i;
        begin
            send_bit(1'b0);
            for (i = 0; i < 8; i = i + 1)
                send_bit(d[i]);
            send_bit(^d);               // 错误的校验位
            send_bit(1'b1);
        end
    endtask
    integer n_ev = 0;
    integer ok = 1;
    always @(posedge clk) begin
        if (ev_valid) begin
            n_ev = n_ev + 1;
            $display("  [ps2] event #%0d: dx=%0d dy=%0d btn=%b", n_ev, $signed(ev_dx), $signed(ev_dy), ev_btn);
            if (n_ev == 1) begin
                if (($signed(ev_dx) != 8) || ($signed(ev_dy) != -8) || (ev_btn != 5'b00000)) begin
                    $display("  [ps2] FAIL: 第 1 包应为 dx=+8 dy=-8 btn=00000（鼠标向上 -> 事件 dy 为负）");
                    ok = 0;
                end
            end
            if (n_ev == 2) begin
                if (($signed(ev_dx) != -3) || ($signed(ev_dy) != 5) || (ev_btn[0] != 1'b1)) begin
                    $display("  [ps2] FAIL: 第 2 包应为 dx=-3 dy=+5 btn=xxxx1（鼠标向下 -> 事件 dy 为正）");
                    ok = 0;
                end
            end
        end
    end
    integer rx_after_bad;
    initial begin
        $display("[ps2] === PS/2 mouse receiver test ===");
        #2000;
        reset = 1'b0;
        #2000;
        $display("[ps2] 校验位错的字节应该被丢掉");
        send_byte_bad_parity(8'h08);
        #(100_000);
        if (rx_count != 16'd0) begin
            $display("  [ps2] FAIL: 校验错的帧不该被计数（rx_count=%0d）", rx_count);
            ok = 0;
        end
        rx_after_bad = rx_count;
        $display("[ps2] packet 1: flag=0x08(no button) dx=+8 dy=+8（鼠标向右上移）");
        send_byte(8'h08);
        send_byte(8'h08);
        send_byte(8'h08);
        #(100_000);
        $display("[ps2] packet 2: flag=0x09(left) dx=-3 dy=-5（向左下移）");
        send_byte(8'h09);
        send_byte(8'hFD);
        send_byte(8'hFB);
        #(100_000);
        $display("[ps2] rx_count=%0d events=%0d", rx_count, n_ev);
        if ((rx_count != rx_after_bad + 16'd6) || (n_ev != 2) || (ok == 0))
            $display("[ps2] === FAIL ===");
        else
            $display("[ps2] === ALL PASS ===");
        $finish;
    end
 endmodule
@@ -215,18 +215,23 @@ module tb_saolei;
        end
    endtask
-    //   g_exit=0x04 g_in_level=0x08 acc_y=0x40C acc_x=0x410 cur_c=0x414
+    //   最新版（显存每格 2 字节、难度三档不同尺寸）变量地址：
-    //   cur_r=0x418 g_first_done=0x420 g_state=0x424
+    //   g_exit=0x04 g_in_level=0x08 acc_y=0x78C acc_x=0x790 cur_c=0x794
-    //   g_evq_lost=0x490 g_evq_tail=0x494 g_evq_head=0x498
+    //   cur_r=0x798 g_difficulty=0x7A0 g_mines=0x7A4 g_first_done=0x7A8
    //   g_state=0x7AC flags_cnt=0x7B0 opened_cnt=0x7B4
    //   flag_bm=0x7F4 open_bm=0x830 mine_bm=0x86C
    //   g_ncells=0x8B4 g_evq_lost=0x8C0 g_evq_tail=0x8C4 g_evq_head=0x8C8
    task dump_vars;
        begin
-            $display("  [vars] exit=%0d in_level=%0d cur=(r%0d,c%0d) acc=(%0d,%0d) first=%0d state=%0d lost=%0d evq(h=%0d,t=%0d)",
+            $display("  [vars] exit=%0d in_level=%0d cur=(r%0d,c%0d) acc=(%0d,%0d) diff=%0d mines=%0d first=%0d state=%0d flags=%0d opened=%0d lost=%0d evq(h=%0d,t=%0d)",
                     dut.ram[32'h0004 >> 2], dut.ram[32'h0008 >> 2],
-                     dut.ram[32'h0418 >> 2], dut.ram[32'h0414 >> 2],
+                     dut.ram[32'h0798 >> 2], dut.ram[32'h0794 >> 2],
-                     dut.ram[32'h0410 >> 2], dut.ram[32'h040C >> 2],
+                     dut.ram[32'h0790 >> 2], dut.ram[32'h078C >> 2],
-                     dut.ram[32'h0420 >> 2], dut.ram[32'h0424 >> 2],
+                     dut.ram[32'h07A0 >> 2], dut.ram[32'h07A4 >> 2],
-                     dut.ram[32'h0490 >> 2],
+                     dut.ram[32'h07A8 >> 2], dut.ram[32'h07AC >> 2],
-                     dut.ram[32'h0498 >> 2], dut.ram[32'h0494 >> 2]);
+                     dut.ram[32'h07B0 >> 2], dut.ram[32'h07B4 >> 2],
                     dut.ram[32'h08C0 >> 2],
                     dut.ram[32'h08C8 >> 2], dut.ram[32'h08C4 >> 2]);
        end
    endtask
@@ -235,7 +240,7 @@ module tb_saolei;
        integer k2, b2;
        begin
            nz_cnt = 0;
-            for (k2 = 0; k2 < 300; k2 = k2 + 1)
+            for (k2 = 0; k2 < 600; k2 = k2 + 1)
                for (b2 = 0; b2 < 4; b2 = b2 + 1)
                    if (dut.fb[k2][b2*8 +: 8] != 8'h00)
                        nz_cnt = nz_cnt + 1;
@@ -247,8 +252,8 @@ module tb_saolei;
            $fwrite(fh, "CURSOR %0d %0d\n", cursor_row, cursor_col);
            $fwrite(fh, "CTRL 0x%02X\n", dut.u_vga.ctrl_i[7:0]);
            $fwrite(fh, "STATS fb_we=%0d nonzero=%0d\n", fb_we_cnt, nz_cnt);
-            $fwrite(fh, "FB 1200\n");
+            $fwrite(fh, "FB 2400\n");
-            for (w = 0; w < 300; w = w + 1)
+            for (w = 0; w < 600; w = w + 1)
                for (b = 0; b < 4; b = b + 1)
                    $fwrite(fh, "%02X\n", dut.fb[w][b*8 +: 8]);
            $fclose(fh);
@@ -261,7 +266,7 @@ module tb_saolei;
    endtask
    // ---------------------------------------------------------------- 完整一局用的工具
-    // 从 RAM 的位图里取一位（mine_bm @0x470 / open_bm @0x450，字内小端）
+    // 从 RAM 的位图里取一位（mine_bm @0x86C / open_bm @0x830 / flag_bm @0x7F4）
    function integer bitof;
        input integer base;
        input integer idx;
@@ -270,14 +275,11 @@ module tb_saolei;
        end
    endfunction
-    // 已揭开格数（直接数 open_bm 的 1），目标 = 256 - 40 = 216
+    // 已揭开格数：直接读程序里的 opened_cnt（0x7B4）
    integer open_n;
    task count_open;
        integer k3;
        begin
-            open_n = 0;
+            open_n = dut.ram[32'h07B4 >> 2];
            for (k3 = 0; k3 < 256; k3 = k3 + 1)
                open_n = open_n + bitof(32'h0000_0450, k3);
        end
    endtask
@@ -376,7 +378,7 @@ module tb_saolei;
                for (cc = 0; cc < 16; cc = cc + 1) begin
                    idx = rr * 16 + cc;
                    goto_cell(rr, cc);
-                    if (bitof(32'h0000_0470, idx) != 0) begin
+                    if (bitof(32'h0000_086C, idx) != 0) begin
                        sw_flag = 1'b1;
                        #(30 * 1000);
                        click_t;
@@ -388,18 +390,20 @@ module tb_saolei;
                    // 中途退出关卡就立即报警并收手
                    if (dut.ram[32'h0008 >> 2] == 0) begin
                        $display("  [game] *** 在盘面 (%0d,%0d) 处退出了关卡！cur=(%0d,%0d) state=%0d",
-                                 rr, cc, dut.ram[32'h0418 >> 2], dut.ram[32'h0414 >> 2],
+                                 rr, cc, dut.ram[32'h0798 >> 2], dut.ram[32'h0794 >> 2],
-                                 dut.ram[32'h0424 >> 2]);
+                                 dut.ram[32'h07AC >> 2]);
                        disable sweep_blk;
                    end
                    // 赢了/输了也收手
-                    if (dut.ram[32'h0424 >> 2] != 0)
+                    if (dut.ram[32'h07AC >> 2] != 0)
                        disable sweep_blk;
                end
                count_open;
-                $display("  [game] 第 %0d 行扫完：已揭开 %0d / 216, state=%0d, 旗=%0d, cur=(%0d,%0d)",
+                $display("  [game] 第 %0d 行扫完：已揭开 %0d / %0d, state=%0d, 旗=%0d, cur=(%0d,%0d)",
-                         rr, open_n, dut.ram[32'h0424 >> 2], dut.ram[32'h0428 >> 2],
+                         rr, open_n,
-                         dut.ram[32'h0418 >> 2], dut.ram[32'h0414 >> 2]);
+                         (dut.ram[32'h08B4 >> 2] - dut.ram[32'h07A4 >> 2]),
                         dut.ram[32'h07AC >> 2], dut.ram[32'h07B0 >> 2],
                         dut.ram[32'h0798 >> 2], dut.ram[32'h0794 >> 2]);
                if (rr == 3)
                    dump_fb("fb_10_sweep_a.txt");
                if (rr == 7)
@@ -424,31 +428,36 @@ module tb_saolei;
        click_t;
        #(2 * 1000000);
        dump_fb("fb_01_level.txt");
-        $display("  [game] 进关卡：in_level=%0d state=%0d", dut.ram[32'h0008 >> 2], dut.ram[32'h0424 >> 2]);
+        $display("  [game] 进关卡：in_level=%0d state=%0d", dut.ram[32'h0008 >> 2], dut.ram[32'h07AC >> 2]);
        // 3) 关卡内点盘面中心一格：放雷 + 首次展开（第一下必安全）
        click;
        #(3 * 1000000);
        dump_fb("fb_02_firstclick.txt");
        count_open;
-        $display("  [game] 首次点击后：first=%0d 已揭开 %0d / 216 state=%0d",
+        $display("  [game] 首次点击后：first=%0d 已揭开 %0d / %0d state=%0d diff=%0d",
-                 dut.ram[32'h0420 >> 2], open_n, dut.ram[32'h0424 >> 2]);
+                 dut.ram[32'h07A8 >> 2], open_n,
                 (dut.ram[32'h08B4 >> 2] - dut.ram[32'h07A4 >> 2]),
                 dut.ram[32'h07AC >> 2], dut.ram[32'h07A0 >> 2]);
        // 4) 蛇形扫完全盘：揭开全部 216 个安全格 + 给 40 颗雷插旗 -> 目标通关
        sweep_board;
        #(3 * 1000000);
        dump_fb("fb_13_after_sweep.txt");
        count_open;
-        $display("  [game] 扫完后：已揭开 %0d / 216, 旗=%0d, state=%0d, 丢事件=%0d",
+        $display("  [game] 扫完后：已揭开 %0d / %0d, 旗=%0d, state=%0d, 丢事件=%0d",
-                 open_n, dut.ram[32'h0428 >> 2], dut.ram[32'h0424 >> 2], dut.ram[32'h0490 >> 2]);
+                 open_n, (dut.ram[32'h08B4 >> 2] - dut.ram[32'h07A4 >> 2]),
                 dut.ram[32'h07B0 >> 2], dut.ram[32'h07AC >> 2], dut.ram[32'h08C0 >> 2]);
        // 5) 通关后再点一下 = 返回背景（回到开始界面）
        click_t;
        #(3 * 1000000);
        dump_fb("fb_14_back_to_start.txt");
-        $display("  [game] === 结束：state=%0d（1=WIN 2=LOSE）已揭开 %0d/216 旗=%0d 丢事件=%0d ===",
+        $display("  [game] === 结束：state=%0d（1=WIN 2=LOSE）已揭开 %0d/%0d 旗=%0d 丢事件=%0d ===",
-                 dut.ram[32'h0424 >> 2], open_n, dut.ram[32'h0428 >> 2], dut.ram[32'h0490 >> 2]);
+                 dut.ram[32'h07AC >> 2], open_n,
                 (dut.ram[32'h08B4 >> 2] - dut.ram[32'h07A4 >> 2]),
                 dut.ram[32'h07B0 >> 2], dut.ram[32'h08C0 >> 2]);
        $finish;
    end
@@ -189,8 +189,8 @@ module tb_saolei_play;
                $fwrite(df, "CURSOR %0d %0d\n",
                        dut.u_vga.cursor_i[12:8], dut.u_vga.cursor_i[4:0]);
                $fwrite(df, "CTRL 0x%02X\n", dut.u_vga.ctrl_i[7:0]);
-                $fwrite(df, "FB 1200\n");
+                $fwrite(df, "FB 2400\n");
-                for (w2 = 0; w2 < 300; w2 = w2 + 1)
+                for (w2 = 0; w2 < 600; w2 = w2 + 1)
                    for (b2 = 0; b2 < 4; b2 = b2 + 1)
                        $fwrite(df, "%02X\n", dut.fb[w2][b2*8 +: 8]);
                $fclose(df);
@@ -34,6 +34,22 @@
 set script_dir [file dirname [file normalize [info script]]]
 set fb2png     [file normalize [file join $script_dir .. .. saolei tools fb2png.py]]
 # 找系统 Python：xsim 的 PATH 里带着 Vivado 自带的 python3.8，直接 exec py 会撞上它
 # （SRE module mismatch），所以用绝对路径优先。
 proc find_python {} {
    foreach ver {314 313 312 311 310} {
        set c [file join $::env(LOCALAPPDATA) Programs Python "Python$ver" python.exe]
        if {[file exists $c]} { return $c }
    }
    return "py"
 }
 set python [find_python]
 # xsim 的进程环境里带着 Vivado 的 PYTHONHOME，会让**系统 python** 也去 Vivado 的
 # lib 里找模块（SRE module mismatch）。清掉它，子进程才不会继承。
 catch { unset ::env(PYTHONHOME) }
 catch { unset ::env(PYTHONPATH) }
 puts "  (python: $python)"
 # 按键字符 -> 人类可读的动作（只用于回显）
 array set KEYNAME {
    c "左键点击"   u "上"   w "上"   d "下"   s "下"
@@ -56,12 +72,12 @@ if {![file exists "cmd.txt"]} {
 # 把 now.txt 渲染到终端（ANSI 彩色棋盘）
 proc render {} {
-    global fb2png
+    global fb2png python
    if {![file exists "now.txt"]} {
        puts "  (now.txt not ready yet - run a bit first)"
        return
    }
-    if {[catch { exec py $fb2png --term now.txt >@stdout 2>@stderr } err]} {
+    if {[catch { exec $python $fb2png --term now.txt >@stdout 2>@stderr } err]} {
        puts "  render failed: $err"
        puts "  try manually: py \"$fb2png\" --term now.txt"
    }
@@ -85,11 +101,11 @@ file mkdir $shot_dir
 set shot_n 0
 proc save_shot {tag} {
-    global fb2png shot_dir
+    global fb2png shot_dir python
    if {![file exists "now.txt"]} { return }
    incr ::shot_n
    set name [format "%s/%03d_%s.png" $shot_dir $::shot_n $tag]
-    if {[catch { exec py $fb2png --quiet now.txt $name } err]} {
+    if {[catch { exec $python $fb2png --quiet now.txt $name } err]} {
        puts "     (screenshot failed: $err)"
        return
    }
@@ -19,7 +19,8 @@ saolei/
 配套硬件在 Vivado 工程里（不在本目录）：`srcs/rtl/cpu21_mmio.v`（外设中枢）、
 `cpu21_vga.v`（显示）、`cpu21_seg7.v`（数码管）、`cpu21_pointer.v`（按键当鼠标）、
-`cpu21_ps2_mouse.v`（可选真鼠标）、`srcs/board/cpu21_board_top.v`（上板顶层）。
+`cpu21_ps2_mouse.v` / `cpu21_ps2_kbd.v`（可选真鼠标/真键盘）、
 `srcs/board/cpu21_board_top.v`（上板顶层）。
 ---
@@ -148,36 +149,58 @@ copy build\saolei.hex <仓库>\pipelined-cpu\srcs\rom\saolei.hex
 `cpu21_board_top.v` 就会加载 `cpu21_saolei_rom.vh`；不定义仍是原来的跑马灯程序。
 接 VGA 显示器，按 `CPU_RESETN` 复位 → 出现开始界面（标题 + 绿色按钮 + 闪动光标框）。
-**操作**（默认用板上 5 向按键）：
+**操作**（板载 5 向按键一直有效）：
-| 操作                                 | 按键                                    |
+| 操作                                 | 板载按键                              | PS/2 设备（SW15 选）                  |
-| ------------------------------------ | --------------------------------------- |
+| ------------------------------------ | ------------------------------------- | ------------------------------------- |
-| 移动光标                             | `BTNU` / `BTND` / `BTNL` / `BTNR`       |
+| 移动光标                             | `BTNU` / `BTND` / `BTNL` / `BTNR` | 键盘 `↑↓←→`（按住 = 连续）/ 鼠标移动 |
-| 左键（揭开；在开始界面上 = 开始）    | `BTNC`                                  |
+| 左键（揭开；开始界面 = 选难度/开始） | `BTNC`                                | 键盘 `Enter`/空格 / 鼠标左键        |
-| 插旗模式（拨上去后左键 = 插/取消旗） | `SW0` 或 `SW3`                          |
+| 右键（插旗 / 取消旗）                | `SW3`（或 `SW0`）拨上 + `BTNC`     | 键盘左 `Shift`/`F`/`C` / 鼠标右键 |
-| 返回上一层（关卡内）                 | 把光标移到盘面**左上角黄格**再按 `BTNC` |
+| 返回上一层（关卡内）                 | 光标移到盘面**左上角黄格**再按左键    | 同上                                  |
-**鼠标**：默认按键；想用真鼠标就把顶层参数 `USE_PS2_MOUSE` 设为 1（需要 Digilent
+**PS/2 键鼠**（板载 USB HOST 口，也可把 Pmod PS/2 插在 JA）：顶层参数
-Pmod PS2 插在 JA + 一个 PS/2 鼠标）。`cpu21_ps2_mouse.v` 只实现了**接收**（发 0xF4
+`USE_PS2_MOUSE` 默认为 1，鼠标解码器和键盘解码器都挂在同一根 PS/2 线上，**用 SW15
-初始化要靠鼠标产生的时钟脉冲，不是固定延时能糊的，所以没写假的）；多数鼠标上电即上报，
+选哪个生效**（0 = 键盘，1 = 鼠标）。键盘解的是扫描码集 2（`E0` 扩展前缀、`F0` 松开
-需要 0xF4 的那种得自己补。USB 鼠标在这个核上不现实（协议栈放不下）。C 程序两种方式
+前缀，只对按下产生事件），映射成与鼠标**完全一样**的事件格式，所以 C 代码一行不用改。
-完全不用改。
+接收器只做**接收**（不实现主机发 `0xF4` 使能上报）：多数键鼠上电即上报。上板时用
 LED 诊断看“当前设备收到的字节数”（见根目录 README 的“PS/2 键鼠”一节）。
 USB 鼠标在这个核上不现实（协议栈放不下）。
 **踩过的坑（值得写进报告）**：`cpu21_ps2_mouse.v` 早期把 11 位帧**整体右移**、又在
 停止位还没移进来时就判 `frame_q[10]`，并且把 PS/2 的**奇**校验当成**偶**校验判，结果
 真设备发来的帧**全部被丢掉** —— 上板表现就是“插上鼠标毫无反应、收到的字节数恒为 0”，
 很容易误判成硬件/跳线问题。现在帧按**位的下标**存（`frame_q[i]` = 第 i 位）、停止位
 单独判（它就在当前拍的 `ps2_data` 上）、校验按奇校验判，并且
 `srcs/tb/tb_ps2_mouse.v` / `tb_ps2_kbd.v` 两个自测里都带“故意发错校验 → 必须丢帧”
 的用例。
 ## 6. 验证状态（说实话）
-| 部分                                                                                 | 状态                                                   |
+| 部分                                                                                 | 状态                                                                             |
-| ------------------------------------------------------------------------------------ | ------------------------------------------------------ |
+| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
-| C 工具链链路                                                                         | 本次修改后未验证：当前环境缺少 RISC-V 交叉编译器       |
+| C 工具链链路                                                                         | 已实测通过：`text=4608 B, data=0, bss=2508 B`，**1152 条指令全部通过 ISA 检查** |
-| `saolei.c` / `isr.c` / `start.c` / `linker.ld`                                       | 本机 GCC 语法检查通过；目标 ISA 构建待工具链恢复后执行 |
+| 游戏逻辑（布雷、`count_adj`、三档难度、`draw_tile`）                                | PC 侧独立测试通过（3 难度 × 40 局重算比对 + 端到端显示测试）                     |
-| `cpu21_mmio.v` 扩展、`cpu21_vga.v`、`cpu21_seg7.v`、`cpu21_pointer.v`、板级顶层、XDC | `xvlog` 编译通过；未综合、未上板                       |
+| 仿真显示（`tb_saolei` / `tb_saolei_play` + `tools/fb2png.py`）                      | 通过：整屏 dump 能还原成 PNG，hard 盘面（30×16）整屏都能画出来                |
 | `cpu21_mmio.v` / `cpu21_vga.v` / `cpu21_seg7.v` / `cpu21_pointer.v` / 板级顶层 / XDC | `xvlog` 编译通过；已综合、已上板                                                |
 | 上板实测                                                                             | VGA 画面、开始界面、三档难度、开格/插旗、板载按键均已实测可用                    |
 | PS/2 键鼠                                                                            | 接收器逻辑有自测（`tb_ps2_mouse` / `tb_ps2_kbd`）；板载 USB HOST 口待复测      |
-建议验证顺序：① 跑 `pipelined-cpu/tools/run_regress.ps1` 确认原来的跑马灯/中断/指令
+建议验证顺序：① 跑 `pipelined-cpu/tools/run_regress.ps1` 确认跑马灯/中断/指令测试仍全
-测试仍全 PASS；② 定义 `SAOLEI_ROM` 跑行为仿真，看有没有往 `0x2000` 起的显存写字节、
+PASS；② 定义 `SAOLEI_ROM` 跑行为仿真（`tb_saolei` 会自动打完一局并 dump 显存）；
-按键后有没有跳进 `0x200`；③ 再上板。
+③ 上板看 VGA；④ 接键鼠时先用 `srcs/tb/tb_ps2_*` 确认解码无误，再看 LED 诊断确认板载
 桥接芯片到底有没有转发你插的那个设备。
 ## 7. 已知可改进项
- **文字显示**：显存现在每格占 2 字节，字形编号扩展到 6 位，RTL 内置 A-Z 和数字/游戏
+- **难度**：已按微软扫雷做成三档 —— `EASY` 9×9/10 雷、`NORMAL` 16×16/40 雷、
-  符号字模，开始界面显示 `MINES`、`EASY`、`NORMAL`、`HARD`、`START`。
+  `HARD` 30×16/99 雷。盘面尺寸是**运行期变量**（`g_bw/g_bh/g_mines/g_ncells`），
- 棋盘固定 16×16，开始界面可选 20/40/60 雷（16 是 2 的幂，索引全用移位，一次除法都不用）。
+  开始界面上点那一行就即时切换、重新画盘面；所有索引走 `IDX_R/IDX_C` 宏。
- `run_regress.ps1` 里还没有扫雷的自动测试项。
+  再想更大就要动 `bfs_q` 的打包方式（数据 RAM 只有 4 KB）。
 - **输入**：板载 5 向按键、PS/2 鼠标、PS/2 键盘三种事件源在顶层合并成同一种格式
  （±8 = 一格），键鼠用 SW15 切换（见上文“操作”）。
 - **文字显示**：显存每格 2 字节（字形[5:0] + 颜色[2:0]），RTL 内置 A-Z 和数字/游戏
  符号字模，开始界面显示 `MINES`、`EASY`、`NORMAL`、`HARD`、`START`。注意**字符颜色
  不能取黑色**（黑字画在黑背景上等于看不见）。
 - 回归覆盖：`run_regress.ps1` 里还没有扫雷的自动测试项（PS/2 接收器有单独的
  `tb_ps2_mouse` / `tb_ps2_kbd`）；也还没有“自动玩一局 + 显存 dump + PNG 比对”的
  一键回归。
@@ -18,13 +18,24 @@
 * ---------------------------------------------------------------------------*/
 #include "mmio.h"
-#define BW 16u                  /* 棋盘宽（格） */
+/* 三档难度完全照微软扫雷：初级 9x9/10 雷、中级 16x16/40 雷、高级 30x16/99 雷。
-#define BH 16u                  /* 棋盘高（格） */
+ * 棋盘尺寸是运行期变量（三档各不相同），所以位图与队列都按最大尺寸分配。 */
-#define NCELLS (BW * BH)        /* 256 */
+#define BW_MAX 30u /* 最大棋盘宽（高级） */
-#define BM_WORDS (NCELLS / 32u) /* 8 */
+#define BH_MAX 16u /* 最大棋盘高 */
 #define NCELLS_MAX (BW_MAX * BH_MAX)            /* 480 */
 #define BM_WORDS_MAX ((NCELLS_MAX + 31u) / 32u) /* 15 */
-#define BOARD_C0 12u /* 棋盘左上角在网格里的列 */
+/* 当前难度下的棋盘参数（由 set_difficulty() 设定） */
-#define BOARD_R0 7u  /* 棋盘左上角在网格里的行 */
+static unsigned g_bw, g_bh; /* 棋盘宽、高（格） */
 static unsigned g_ncells;   /* g_bw * g_bh */
 static unsigned g_bm_words; /* 位图字数 */
 static unsigned g_board_r0; /* 棋盘左上角在网格里的行（居中） */
 static unsigned g_board_c0; /* 棋盘左上角在网格里的列（居中） */
 /* 格索引 <-> (行, 列)。这颗核有无符号除法 divu/remu，直接用；虽然多周期，
 * 但一局游戏这点开销无所谓。 */
 #define IDX_R(i) ((i) / g_bw)
 #define IDX_C(i) ((i) % g_bw)
 /* 游戏状态 */
 #define ST_PLAY 0u
@@ -32,9 +43,10 @@
 #define ST_LOSE 2u
 /* ---- 棋盘状态：3 个位图，每个 8 个字（256 位） ---- */
-static unsigned mine_bm[BM_WORDS];
+static unsigned mine_bm[BM_WORDS_MAX];
-static unsigned open_bm[BM_WORDS];
+static unsigned open_bm[BM_WORDS_MAX];
-static unsigned flag_bm[BM_WORDS];
+static unsigned flag_bm[BM_WORDS_MAX];
 static unsigned seen_bm[BM_WORDS_MAX]; /* BFS：已经入过队的格子，避免重复入队把队列撑满 */
 /* 其它全局状态（全部进 .bss，靠 start.c 清零） */
 static unsigned opened_cnt;
@@ -46,7 +58,7 @@ static unsigned g_difficulty;
 static unsigned rnd_state;
 static unsigned cur_r, cur_c;  /* 光标所在的网格格 */
 static int acc_x, acc_y;       /* 指针累积量（1/8 格，有符号） */
-static unsigned bfs_q[NCELLS]; /* 揭开用的队列 */
+static unsigned bfs_q[NCELLS_MAX]; /* 揭开用的队列（按最大棋盘分配） */
 /* ============================ 小工具 ============================ */
@@ -74,7 +86,7 @@ static void draw_cell(unsigned gr, unsigned gc, unsigned glyph, unsigned color)
 /* 把棋盘格 (r,c) 画出来 */
 static void draw_tile(unsigned r, unsigned c, unsigned glyph, unsigned color)
 {
-    draw_cell(BOARD_R0 + r, BOARD_C0 + c, glyph, color);
+    draw_cell(g_board_r0 + r, g_board_c0 + c, glyph, color);
 }
 static unsigned num_color(unsigned n)
@@ -96,20 +108,20 @@ static unsigned num_color(unsigned n)
 static unsigned in_board(void)
 {
-    if (cur_r < BOARD_R0)
+    if (cur_r < g_board_r0)
        return 0u;
-    if (cur_r >= (BOARD_R0 + BH))
+    if (cur_r >= (g_board_r0 + g_bh))
        return 0u;
-    if (cur_c < BOARD_C0)
+    if (cur_c < g_board_c0)
        return 0u;
-    if (cur_c >= (BOARD_C0 + BW))
+    if (cur_c >= (g_board_c0 + g_bw))
        return 0u;
    return 1u;
 }
 static unsigned cur_index(void)
 {
-    return ((cur_r - BOARD_R0) << 4) + (cur_c - BOARD_C0); /* *BW(=16) 用移位 */
+    return ((cur_r - g_board_r0) * g_bw) + (cur_c - g_board_c0);
 }
 /* LCG 随机数：只用 mul/add/移位 */
@@ -119,13 +131,32 @@ static unsigned rnd_next(void)
    return rnd_state >> 16;
 }
-static unsigned difficulty_mines(unsigned difficulty)
+/* 设定难度：棋盘尺寸 + 雷数 + 居中位置，三档完全照微软扫雷。 */
 static void set_difficulty(unsigned difficulty)
 {
-    if (difficulty == 0u)
+    g_difficulty = difficulty;
-        return 20u;
+    if (difficulty == 0u) /* 初级：9x9，10 雷 */
-    if (difficulty == 2u)
+    {
-        return 60u;
+        g_bw = 9u;
-    return 40u;
+        g_bh = 9u;
        g_mines = 10u;
    }
    else if (difficulty == 2u) /* 高级：30x16，99 雷 */
    {
        g_bw = 30u;
        g_bh = 16u;
        g_mines = 99u;
    }
    else /* 中级：16x16，40 雷 */
    {
        g_bw = 16u;
        g_bh = 16u;
        g_mines = 40u;
    }
    g_ncells = g_bw * g_bh;
    g_bm_words = (g_ncells + 31u) / 32u;
    g_board_c0 = (GRID_COLS - g_bw) / 2u; /* 棋盘居中 */
    g_board_r0 = (GRID_ROWS - g_bh) / 2u;
 }
 /* ============================ 画面 ============================ */
@@ -142,24 +173,24 @@ static void clear_screen(void)
 static void draw_frame(void)
 {
    unsigned gc, gr;
-    for (gc = (BOARD_C0 - 1u); gc <= (BOARD_C0 + BW); gc = gc + 1u)
+    for (gc = (g_board_c0 - 1u); gc <= (g_board_c0 + g_bw); gc = gc + 1u)
    {
-        draw_cell(BOARD_R0 - 1u, gc, G_SOLID, C_CYAN);
+        draw_cell(g_board_r0 - 1u, gc, G_SOLID, C_CYAN);
-        draw_cell(BOARD_R0 + BH, gc, G_SOLID, C_CYAN);
+        draw_cell(g_board_r0 + g_bh, gc, G_SOLID, C_CYAN);
    }
-    for (gr = (BOARD_R0 - 1u); gr <= (BOARD_R0 + BH); gr = gr + 1u)
+    for (gr = (g_board_r0 - 1u); gr <= (g_board_r0 + g_bh); gr = gr + 1u)
    {
-        draw_cell(gr, BOARD_C0 - 1u, G_SOLID, C_CYAN);
+        draw_cell(gr, g_board_c0 - 1u, G_SOLID, C_CYAN);
-        draw_cell(gr, BOARD_C0 + BW, G_SOLID, C_CYAN);
+        draw_cell(gr, g_board_c0 + g_bw, G_SOLID, C_CYAN);
    }
 }
 static void draw_all_covered(void)
 {
    unsigned r, c;
-    for (r = 0u; r < BH; r = r + 1u)
+    for (r = 0u; r < g_bh; r = r + 1u)
    {
-        for (c = 0u; c < BW; c = c + 1u)
+        for (c = 0u; c < g_bw; c = c + 1u)
        {
            draw_tile(r, c, G_COVER, C_GRAY);
        }
@@ -168,7 +199,8 @@ static void draw_all_covered(void)
 static void update_cursor_reg(void)
 {
-    REG_W(REG_CURSOR) = (cur_c & 31u) | ((cur_r & 31u) << 8);
+    /* 列用 6 位（0..39）：hard 棋盘宽 30，光标列能到 35，掩 31 会把它变成 3 */
    REG_W(REG_CURSOR) = (cur_c & 63u) | ((cur_r & 31u) << 8);
 }
 static void set_bg(unsigned color)
@@ -180,11 +212,11 @@ static void set_bg(unsigned color)
 static unsigned count_adj(unsigned i)
 {
-    unsigned r = i >> 4, c = i & 15u, n = 0u, rr, cc;
+    unsigned r = IDX_R(i), c = IDX_C(i), n = 0u, rr, cc;
    unsigned r0 = (r == 0u) ? 0u : (r - 1u);
-    unsigned r1 = (r + 1u >= BH) ? (BH - 1u) : (r + 1u);
+    unsigned r1 = (r + 1u >= g_bh) ? (g_bh - 1u) : (r + 1u);
    unsigned c0 = (c == 0u) ? 0u : (c - 1u);
-    unsigned c1 = (c + 1u >= BW) ? (BW - 1u) : (c + 1u);
+    unsigned c1 = (c + 1u >= g_bw) ? (g_bw - 1u) : (c + 1u);
    for (rr = r0; rr <= r1; rr = rr + 1u)
    {
@@ -192,7 +224,7 @@ static unsigned count_adj(unsigned i)
        {
            if ((rr == r) && (cc == c))
                continue;
-            n = n + bget(mine_bm, (rr << 4) + cc);
+            n = n + bget(mine_bm, (rr * g_bw) + cc);
        }
    }
    return n;
@@ -201,17 +233,17 @@ static unsigned count_adj(unsigned i)
 static void lose(unsigned hit)
 {
    unsigned k;
-    for (k = 0u; k < NCELLS; k = k + 1u)
+    for (k = 0u; k < g_ncells; k = k + 1u)
    {
        if (bget(mine_bm, k))
        {
            if (k == hit)
            {
-                draw_tile(k >> 4, k & 15u, G_BOOM, C_RED);
+                draw_tile(IDX_R(k), IDX_C(k), G_BOOM, C_RED);
            }
            else if (!bget(flag_bm, k))
            {
-                draw_tile(k >> 4, k & 15u, G_MINE, C_RED);
+                draw_tile(IDX_R(k), IDX_C(k), G_MINE, C_RED);
            }
        }
    }
@@ -222,11 +254,11 @@ static void lose(unsigned hit)
 static void win(void)
 {
    unsigned k;
-    for (k = 0u; k < NCELLS; k = k + 1u)
+    for (k = 0u; k < g_ncells; k = k + 1u)
    {
        if (bget(mine_bm, k))
        {
-            draw_tile(k >> 4, k & 15u, G_FLAG, C_YELLOW);
+            draw_tile(IDX_R(k), IDX_C(k), G_FLAG, C_YELLOW);
        }
    }
    REG_W(LED_ADDR) = 0xF00Du;
@@ -236,7 +268,7 @@ static void win(void)
 static void reveal_at(unsigned i)
 {
    unsigned qh = 0u, qt = 0u, cur, n, r, c, rr, cc, ni;
-    unsigned r0, r1, c0, c1;
+    unsigned r0, r1, c0, c1, k;
    if (bget(open_bm, i) || bget(flag_bm, i))
        return;
@@ -246,8 +278,12 @@ static void reveal_at(unsigned i)
        return;
    }
    for (k = 0u; k < g_bm_words; k = k + 1u)
        seen_bm[k] = 0u;
    bfs_q[qt] = i;
    qt = qt + 1u;
    bset(seen_bm, i);
    while (qh < qt)
    {
@@ -260,27 +296,30 @@ static void reveal_at(unsigned i)
        opened_cnt = opened_cnt + 1u;
        n = count_adj(cur);
-        draw_tile(cur >> 4, cur & 15u, n, num_color(n));
+        draw_tile(IDX_R(cur), IDX_C(cur), n, num_color(n));
        if (n != 0u)
            continue;
-        /* 空白格：把周围 8 格入队（队列有界，满了就丢，不会越界） */
+        /* 空白格：把周围 8 格入队（已入过队的跳过，队列不会溢出） */
-        r = cur >> 4;
+        r = IDX_R(cur);
-        c = cur & 15u;
+        c = IDX_C(cur);
        r0 = (r == 0u) ? 0u : (r - 1u);
-        r1 = (r + 1u >= BH) ? (BH - 1u) : (r + 1u);
+        r1 = (r + 1u >= g_bh) ? (g_bh - 1u) : (r + 1u);
        c0 = (c == 0u) ? 0u : (c - 1u);
-        c1 = (c + 1u >= BW) ? (BW - 1u) : (c + 1u);
+        c1 = (c + 1u >= g_bw) ? (g_bw - 1u) : (c + 1u);
        for (rr = r0; rr <= r1; rr = rr + 1u)
        {
            for (cc = c0; cc <= c1; cc = cc + 1u)
            {
                if ((rr == r) && (cc == c))
                    continue;
-                ni = (rr << 4) + cc;
+                ni = (rr * g_bw) + cc;
-                if (qt < NCELLS)
+                if (bget(seen_bm, ni) || bget(open_bm, ni) || bget(flag_bm, ni))
                    continue;
                if (qt < NCELLS_MAX)
                {
                    bset(seen_bm, ni);
                    bfs_q[qt] = ni;
                    qt = qt + 1u;
                }
@@ -288,21 +327,21 @@ static void reveal_at(unsigned i)
        }
    }
-    if (opened_cnt == (NCELLS - g_mines))
+    if (opened_cnt == (g_ncells - g_mines))
        win();
 }
 static void place_mines(unsigned safe)
 {
    unsigned placed = 0u, i, r, c;
-    unsigned sr = safe >> 4;
+    unsigned sr = IDX_R(safe);
-    unsigned sc = safe & 15u;
+    unsigned sc = IDX_C(safe);
    while (placed < g_mines)
    {
-        i = rnd_next() & 255u; /* NCELLS = 256，正好 2 的幂，不需要取模 */
+        i = rnd_next() % g_ncells; /* 尺寸不再是 2 的幂，用 remu 取模 */
-        r = i >> 4;
+        r = IDX_R(i);
-        c = i & 15u;
+        c = IDX_C(i);
        /* 首点及其 8 邻居不放雷，保证第一次点击一定能展开 */
        if ((r + 1u >= sr) && (r <= (sr + 1u)) &&
            (c + 1u >= sc) && (c <= (sc + 1u)))
@@ -342,8 +381,8 @@ static void toggle_flag(void)
    if (bget(open_bm, i))
        return;
-    r = cur_r - BOARD_R0;
+    r = cur_r - g_board_r0;
-    c = cur_c - BOARD_C0;
+    c = cur_c - g_board_c0;
    if (bget(flag_bm, i))
    {
@@ -368,14 +407,14 @@ static void move_cursor(int dr, int dc)
    int nr = (int)cur_r + dr;
    int nc = (int)cur_c + dc;
-    if (nr < (int)(BOARD_R0 - 1u))
+    if (nr < (int)(g_board_r0 - 1u))
-        nr = (int)(BOARD_R0 - 1u);
+        nr = (int)(g_board_r0 - 1u);
-    if (nr > (int)(BOARD_R0 + BH))
+    if (nr > (int)(g_board_r0 + g_bh))
-        nr = (int)(BOARD_R0 + BH);
+        nr = (int)(g_board_r0 + g_bh);
-    if (nc < (int)(BOARD_C0 - 1u))
+    if (nc < (int)(g_board_c0 - 1u))
-        nc = (int)(BOARD_C0 - 1u);
+        nc = (int)(g_board_c0 - 1u);
-    if (nc > (int)(BOARD_C0 + BW))
+    if (nc > (int)(g_board_c0 + g_bw))
-        nc = (int)(BOARD_C0 + BW);
+        nc = (int)(g_board_c0 + g_bw);
    cur_r = (unsigned)nr;
    cur_c = (unsigned)nc;
@@ -437,19 +476,19 @@ static void handle_event(unsigned ev)
        {
            if (cur_r == DIFF_EASY_R)
            {
-                g_difficulty = 0u;
+                set_difficulty(0u);
                draw_start_screen();
                return;
            }
            if (cur_r == DIFF_NORMAL_R)
            {
-                g_difficulty = 1u;
+                set_difficulty(1u);
                draw_start_screen();
                return;
            }
            if (cur_r == DIFF_HARD_R)
            {
-                g_difficulty = 2u;
+                set_difficulty(2u);
                draw_start_screen();
                return;
            }
@@ -457,11 +496,10 @@ static void handle_event(unsigned ev)
            if ((cur_r == START_R) && (cur_c >= START_C0) && (cur_c <= START_C1))
            {
                g_in_level = 1u; /* 关卡程序返回时自己清 0 */
                g_mines = difficulty_mines(g_difficulty);
                REG_W(REG_LEVEL) = 1u;
            }
        }
-        else if ((cur_r == (BOARD_R0 - 1u)) && (cur_c == (BOARD_C0 - 1u)))
+        else if ((cur_r == (g_board_r0 - 1u)) && (cur_c == (g_board_c0 - 1u)))
        {
            g_exit = 1u; /* 关卡：点左上角黄格 = 返回上一层 */
        }
@@ -568,11 +606,14 @@ static void draw_start_screen(void)
        draw_cell(START_R, i, G_SOLID, C_GREEN);
        draw_cell(START_R + 1u, i, G_BAR, C_YELLOW);
    }
-    draw_cell(START_R, 17u, G_S, C_BLACK);
+    /* 按钮上的字母不能用 C_BLACK：VGA 里像素色 = 字模点 ? 字符色 : 背景色，
-    draw_cell(START_R, 18u, G_T, C_BLACK);
+     * 而背景是黑的，所以“黑字”的字形点和空白处全黑 —— 整格完全看不见。
-    draw_cell(START_R, 19u, G_A, C_BLACK);
+     * 这里用黄色：黑底黄字，和上下的黄线框也更呼应。 */
-    draw_cell(START_R, 20u, G_R, C_BLACK);
+    draw_cell(START_R, 17u, G_S, C_YELLOW);
-    draw_cell(START_R, 21u, G_T, C_BLACK);
+    draw_cell(START_R, 18u, G_T, C_YELLOW);
    draw_cell(START_R, 19u, G_A, C_YELLOW);
    draw_cell(START_R, 20u, G_R, C_YELLOW);
    draw_cell(START_R, 21u, G_T, C_YELLOW);
    /* 下方提示条 */
    for (i = 12u; i <= 27u; i = i + 1u)
@@ -598,19 +639,19 @@ static void draw_start_screen(void)
 *   -> 点左上角黄格 = 返回：清 LEVEL、return -> isr1_entry 恢复现场并 uret
 *   -> 回到背景程序被打断的那条指令，继续等下一次"开始"。
 * ========================================================================== */
-#define RET_R (BOARD_R0 - 1u)
+/* 关卡里“返回上一层”的黄格 = 棋盘左上角外面一格（随难度尺寸移动） */
 #define RET_C (BOARD_C0 - 1u)
 void level_main(void)
 {
    unsigned r;
    /* ---- 关卡初始化 ---- */
-    for (r = 0u; r < BM_WORDS; r = r + 1u)
+    for (r = 0u; r < g_bm_words; r = r + 1u)
    {
        mine_bm[r] = 0u;
        open_bm[r] = 0u;
        flag_bm[r] = 0u;
        seen_bm[r] = 0u;
    }
    opened_cnt = 0u;
    flags_cnt = 0u;
@@ -619,13 +660,13 @@ void level_main(void)
    g_exit = 0u;
    acc_x = 0;
    acc_y = 0;
-    cur_r = BOARD_R0 + 8u;
+    cur_r = g_board_r0 + (g_bh / 2u); /* 光标从棋盘中心开始 */
-    cur_c = BOARD_C0 + 8u;
+    cur_c = g_board_c0 + (g_bw / 2u);
    clear_screen();
    draw_frame();
    draw_all_covered();
-    draw_cell(RET_R, RET_C, G_BAR, C_YELLOW); /* 左上角黄格 = 返回 */
+    draw_cell(g_board_r0 - 1u, g_board_c0 - 1u, G_BAR, C_YELLOW); /* 左上角黄格 = 返回 */
    set_bg(C_BLACK);
    update_cursor_reg();
    REG_W(LED_ADDR) = g_mines;
@@ -680,7 +721,7 @@ int main(void)
    crt_zero_bss(); /* 清 .bss（上电 RAM 本来就是 0，保险起见） */
    rnd_state = REG_R(REG_TIME) | 1u; /* 用自由计数器当随机种子 */
-    g_difficulty = 1u;                /* 默认普通：40 颗雷 */
+    set_difficulty(1u);               /* 默认中级：16x16，40 颗雷 */
    REG_W(REG_MCTRL) = 1u;            /* 打开鼠标中断（IRQ2，入口 0x200） */
    REG_W(REG_LEVEL) = 0u;            /* 清关卡软中断 */
@@ -9,43 +9,70 @@
 dump 格式（tb_saolei.v 里的 dump_fb 任务生成）:
    CURSOR <row> <col>
    CTRL 0x<byte>            # [0] 光标可见  [6:4] 背景色
-    FB 1200                  # 随后 1200 行十六进制字节，按格号 0..1199
+    FB 2400                  # 随后 2400 行十六进制字节：每格 2 字节（字形、颜色）
-渲染依据（与 RTL 严格对应，改 RTL 时这两个表要同步）:
+渲染依据（与 RTL 严格对应）:
-  * 字库 cpu21_vga.v 的 font_row()：8x8、bit7 是最左像素，放大 2 倍 = 16x16 一格
+  * 字库：直接从 cpu21_vga.v 的 font_row() 解析（8x8、bit7 最左，放大 2 倍 = 16x16 一格）
    —— RTL 改了字库（比如新增 A-Z）这里会自动跟随，不用手工抄表
  * 调色板 cpu21_vga.v 的 pal()：3 位 -> 4:4:4 RGB（0xA 分量 = 170）
  * 显存每格 2 字节：byte0 = 字形[5:0]，byte1 = 颜色[2:0]
  * 光标 cpu21_vga.v 的 cursor_box：格子四边一圈 2 像素宽的黄色框（常亮）
  * 画面 40x30 格 -> 640x480
 另外还会在终端打印一份 ASCII 图，方便在没有图片查看器的地方快速看结果。
 """
 import os
 import re
 import struct
 import sys
 import zlib
 COLS, ROWS = 40, 30
 CELL_PX = 16            # 8x8 字模放大 2 倍
 FB_BYTES = COLS * ROWS * 2      # 每格 2 字节（字形 + 颜色）= 2400
-# --- 字库（8 行/字，bit7 = 最左），抄自 cpu21_vga.v 的 font_row() ---
+RTL_VGA = os.path.normpath(os.path.join(os.path.dirname(os.path.abspath(__file__)),
-FONT = {
+                                        "..", "..", "pipelined-cpu", "srcs", "rtl",
-    0:  [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00],  # 空白
+                                        "cpu21_vga.v"))
-    1:  [0x18, 0x38, 0x18, 0x18, 0x18, 0x18, 0x7E, 0x00],  # 1
+
-    2:  [0x3C, 0x66, 0x06, 0x0C, 0x18, 0x30, 0x7E, 0x00],  # 2
+
-    3:  [0x3C, 0x66, 0x06, 0x1C, 0x06, 0x66, 0x3C, 0x00],  # 3
+def load_font_from_rtl(path=None):
-    4:  [0x0C, 0x1C, 0x3C, 0x6C, 0x7E, 0x0C, 0x0C, 0x00],  # 4
+    """直接从 cpu21_vga.v 的 font_row() 里解析 8x8 字模，返回 {字形号: [8 行]}。
-    5:  [0x7E, 0x60, 0x7C, 0x06, 0x06, 0x66, 0x3C, 0x00],  # 5
+
-    6:  [0x1C, 0x30, 0x60, 0x7C, 0x66, 0x66, 0x3C, 0x00],  # 6
+    RTL 里每个字形形如
-    7:  [0x7E, 0x66, 0x0C, 0x18, 0x18, 0x18, 0x18, 0x00],  # 7
+        6'd16: font_row = (r == 3'd0) ? 8'h7C : (r == 3'd1) ? 8'h66 : ... ;
-    8:  [0x3C, 0x66, 0x66, 0x3C, 0x66, 0x66, 0x3C, 0x00],  # 8
+    或全部相同行时形如
-    9:  [0xFF, 0x81, 0xBD, 0xA5, 0xA5, 0xBD, 0x81, 0xFF],  # 未揭开
+        6'd15: font_row = 8'hFF;
-    10: [0x40, 0x70, 0x78, 0x70, 0x40, 0x40, 0x40, 0x00],  # 旗
+    两种情况都能解析。
-    11: [0x3C, 0x7E, 0xFF, 0xFF, 0xFF, 0xFF, 0x7E, 0x3C],  # 雷
+    """
-    12: [0x81, 0x42, 0x24, 0x18, 0x18, 0x24, 0x42, 0x81],  # 爆炸
+    path = path or RTL_VGA
-    13: [0x3C, 0x66, 0x06, 0x0C, 0x18, 0x00, 0x18, 0x00],  # 问号
+    try:
-    14: [0x00, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0x00],  # 横线
+        with open(path, encoding="utf-8", errors="replace") as f:
-    15: [0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF],  # 实心
+            text = f.read()
-}
+    except OSError as e:
        raise SystemExit("读不到 RTL 字库 %s：%s" % (path, e))
    m = re.search(r"function\s*\[7:0\]\s*font_row.*?endfunction", text, re.S)
    if not m:
        raise SystemExit("%s 里找不到 font_row()" % path)
    font = {}
    parts = re.split(r"6'd(\d+)\s*:", m.group(0))
    for i in range(1, len(parts) - 1, 2):       # 奇数下标是字形号，后一格是它的分支体
        idx, seg = int(parts[i]), parts[i + 1]
        rows = [0] * 8
        pairs = re.findall(r"\(r == 3'd(\d+)\)\s*\?\s*8'h([0-9A-Fa-f]{2})", seg)
        if pairs:
            for k, v in pairs:
                rows[int(k)] = int(v, 16)
        else:                                    # 形如 "font_row = 8'hFF;"：8 行一样
            one = re.search(r"font_row\s*=\s*8'h([0-9A-Fa-f]{2})", seg)
            if one:
                rows = [int(one.group(1), 16)] * 8
        font[idx] = rows
    if not font:
        raise SystemExit("%s 的 font_row() 没解析出任何字形" % path)
    return font
 # --- 调色板（3 位 -> RGB），抄自 cpu21_vga.v 的 pal()，4 位分量按 *17 扩到 8 位 ---
 PAL = [
@@ -98,18 +125,24 @@ def parse_dump(path):
                    fb.append(int(line, 16))
                except ValueError:
                    pass
-    if len(fb) != 1200:
+    if len(fb) != FB_BYTES:
-        raise SystemExit("显存字节数不对：%d（应为 1200）" % len(fb))
+        raise SystemExit("显存字节数不对：%d（应为 %d；新版每格 2 字节）"
                         % (len(fb), FB_BYTES))
    return cur, ctrl, fb
 def cell_of(fb, idx):
    """第 idx 格 -> (字形, 颜色)：byte0 = 字形[5:0]，byte1 = 颜色[2:0]。"""
    return fb[2 * idx] & 0x3F, fb[2 * idx + 1] & 0x07
 def cell_char(g):
-    """字形号 -> 一个可见字符（字形 1..8 就是数字 1..8）。"""
+    """字形号 -> 一个可见字符（1..8 数字，16..41 = A-Z，其余见 GLYPH_CH）。"""
-    if g in GLYPH_CH:
+    if 16 <= g <= 41:
-        return GLYPH_CH[g]
+        return chr(ord('A') + g - 16)
    if 1 <= g <= 8:
-        return chr(ord('0') + g)
+        return str(g)
-    return ' '
+    return GLYPH_CH.get(g, '?')
 def dump_note(path):
@@ -140,8 +173,7 @@ def draw_term(fb, cur, cursor_box, note=""):
    for y in range(ROWS):
        cells = []
        for x in range(COLS):
-            cell = fb[y * COLS + x]
+            g, c = cell_of(fb, y * COLS + x)
            g, c = cell & 0xF, (cell >> 4) & 0x7
            r, gg, b = PAL[c]
            ch = cell_char(g)
            if cursor_box and (x, y) == cur:
@@ -151,7 +183,7 @@ def draw_term(fb, cur, cursor_box, note=""):
                cells.append("\x1b[38;2;%d;%d;%dm%s" % (r * 17, gg * 17, b * 17, ch))
        out.append("%2d  " % y + "".join(cells) + "\x1b[0m\n")
    out.append("\x1b[0m")
-    out.append("图例： #=未揭开  P=旗  *=雷  X=爆炸  ?=问号  1..8=数字  空格=已揭开的空地；反色格 = 光标\n")
+    out.append("图例： #=未揭开  P=旗  *=雷  X=爆炸  A-Z=文字  1..8=数字  空格=已揭开的空地；反色格 = 光标\n")
    sys.stdout.write("".join(out))
    sys.stdout.flush()
@@ -165,13 +197,13 @@ def main():
    if quiet:
        args.remove("--quiet")
    if quiet:                               # 只出图不说话（给脚本批量截图用）
        import os
        sys.stdout = open(os.devnull, "w")
    if not args:
        raise SystemExit(__doc__)
    src = args[0]
    dst = args[1] if len(args) > 1 else src.rsplit(".", 1)[0] + ".png"
    cur, ctrl, fb = parse_dump(src)
    font = load_font_from_rtl()
    bg = (ctrl >> 4) & 0x7
    cursor_box = bool(ctrl & 1) and cur[0] is not None
@@ -190,9 +222,8 @@ def main():
        cy, fy = y // CELL_PX, (y % CELL_PX) // 2
        for x in range(COLS * CELL_PX):
            cx, fx = x // CELL_PX, (x % CELL_PX) // 2
-            cell = fb[cy * COLS + cx]
+            g, c = cell_of(fb, cy * COLS + cx)
-            g, c = cell & 0xF, (cell >> 4) & 0x7
+            px_on = (font.get(g, [0] * 8)[fy] >> (7 - fx)) & 1
            px_on = (FONT[g][fy] >> (7 - fx)) & 1
            col = c if px_on else bg
            if cursor_box and (cx, cy) == cur:
                # 光标格：四边 2 像素黄色框，与 cpu21_vga.v 的 cursor_box 一致
Author	SHA1	Message	Date
Alpha	1e5cb54c00	docs(readme): 记录上板实测出来的 PS/2 方向约定（鼠标 dy 取负）上板已经确认：不定负号的表现就是“左右正常、上下反向”，不是解码错；另外把“键鼠静止时一个字节都不发”写成显式提醒，避免再被误判成硬件坏。	2026-09-23 22:50:29 +08:00
Alpha	28c696ece2	fix(ps2): 鼠标 dy 方向取负（PS/2 正 dy = 上，软件正 dy = 下）；键盘补 W/A/S/D 别名上板实测：鼠标已能操作（说明“奇校验 + 帧按位的下标对齐”那个修复就是根因），但上下是反的、左右正确 —— 这是两套约定的差异，不是解码错： * PS/2 鼠标原生约定：dx 正 = 右、dy 正 = 上 * saolei.c 的约定：正 dx = 列 +1、正 dy = 行 +1（向下），和 cpu21_pointer 的 BTND = +8 一致所以 cpu21_ps2_mouse 在拼包时把 dy 取负（dx 不动），三种事件源（板载按键 / PS/2 鼠标 / PS/2 键盘）方向统一。键盘：另加 W/A/S/D = 方向键（与 tools/play_saolei.tcl 里的别名保持一致），这样用普通字母键也能测。自测同步更新（都 ALL PASS）： * tb_ps2_mouse：改发“鼠标向上”的 dy=+8，事件里必须得到 dy=-8；向下 dy=-5 -> +5 * tb_ps2_kbd：新增 W(1D) -> dy=-8 用例	2026-09-23 22:50:19 +08:00
Alpha	9dfff16794	feat(board): 支持 PS/2 键盘（与鼠标共用板载 USB HID 口），并修好 PS/2 帧校验一、修 PS/2 接收器的真 bug —— 这就是上板“鼠标毫无反应”的根因鼠标和键盘两个接收模块原来是同一个写法错误： * 帧用整体右移 {data, frame_q[10:1]}，判 frame_q[10] 时停止位还没移进来，判到的其实是校验位；取数据 frame_q[8:1] 也因此整体错一位 * 校验位按“偶校验”判，而 PS/2 是“奇校验” 两者叠加让真设备发来的帧 100% 被丢掉（上板表现为 rx_count 恒为 0，看起来像硬件或跳线问题）。现在按“位的下标”存帧（frame_q[i] = 第 i 位，所以字节 = frame_q[8:1]、校验 = frame_q[9]），停止位直接在当前拍的 ps2_data 上判，校验按奇校验。二、新增 PS/2 键盘解码 cpu21_ps2_kbd.v 扫描码集 2：E0 = 扩展前缀、F0 = 松开前缀，只对“按下”产生事件，并映射成与鼠标完全相同的事件格式（↑↓←→ = dy/dx ±8，正好一格；Enter/空格 = 左键；左 Shift/F/C = 右键 = 插旗），所以 saolei 的 C 代码一行都不用改；按住方向键 = 连续移动（用的是键盘自己的重复码）。三、顶层 cpu21_board_top：用 SW15 选设备同一根 PS/2 线上只会插一个设备，但两个解码器都在听：键盘的扫描码会凑巧组成 “合法的鼠标包”，两路同时生效会让光标乱跳。因此新增端口 hid_sel(SW15)： 0 = 键盘（默认），1 = 鼠标；诊断 LED 改显示“当前选中设备”收到的字节数。四、其它 * XDC：hid_sel -> V10（SW15），引脚号在官方母版里核对过 * tb_board_top 补 hid_sel 端口，避免悬空 * 新增自测 srcs/tb/tb_ps2_mouse.v / tb_ps2_kbd.v：含“故意发一个校验位错的帧，必须丢帧”的用例，两个都 ALL PASS * README / saolei/README：新增“PS/2 键鼠”一节（接线方式、SW15、LED 诊断口诀、键位表），修正显存格式（每格 2 字节、0x2000-0x2FFF）、扫雷难度与验证状态、修好 riscv 工具链 -Prefix 路径	2026-09-23 22:35:50 +08:00
Alpha	9bbe6bc7eb	debug(board): PS/2 诊断升级 —— 用 LED 直接看两根线的电平与活动上板现象：板载按键正常（事件链没问题），USB HOST 口插罗技鼠标后 rx_count 一直是 0。为了区分"芯片根本没发数据"和"我们的解码有问题"，把 LED 高位改成： LED[15:6] = PS/2 收到的字节数低 10 位 LED[5] = ps2_clk 有边沿活动（时钟在动就快速翻转） LED[4] = ps2_data 当前电平 LED[3] = ps2_clk 当前电平 LED[2:0] 仍是三路中断指示（顺带确认：F4/B2 在官方母版里只属于 USB HID (PS/2)，没有被 SD/以太网等复用。）	2026-09-23 22:03:50 +08:00
Alpha	77dd102675	feat(board): 板载 USB HID 口接 PS/2 鼠标，与板载按键并存 Nexys4DDR 的 USB HOST 口由板上芯片把 USB 键鼠转成 PS/2 信号（官方母版 Nexys4DDR_Master.xdc 标明 ps2_clk = F4、ps2_data = B2），所以不用写 USB 协议栈。 - cpu21_board_top.v： * USE_PS2_MOUSE 默认打开；原来是 if/else 二选一（选鼠标就没按键），现在 cpu21_pointer 与 cpu21_ps2_mouse 同时例化，两路事件在顶层合并成 ev_valid/ ev_dx/ev_dy/ev_btn（同拍优先 PS/2），板载按键一个不删 * 新增 DEBUG_PS2_RX_LED（默认 1）：把 PS/2 收到的字节数显示到 LED[15:3] （LED[2:0] 仍是中断指示）。没有调试器时靠它判断 PS/2 到底有没有数据：鼠标一动数字就跳 = 通了；一直是 0 = 根本没收到 - cpu21_board_top.xdc：ps2_clk/ps2_data 从 Pmod JA（C17/D18）改到板载 USB HID （F4/B2），并在注释里留了改回 Pmod 的方法软件侧不用改：鼠标事件与按键事件格式相同，且 PS/2 的 dx/dy 天然满足 "8 个计数 = 一格"（saolei.c 里就是 acc_x += dx; while (acc_x >= 8) 移动一格）。额外好处：鼠标右键 = 插旗（handle_event 本来就支持）。	2026-09-23 21:50:18 +08:00
Alpha	64428bdd85	feat(tools): 仿真调试台适配新版显存，并修好 xsim 里跑 python 的环境问题 tb_saolei.v / tb_saolei_play.v： - dump 从 1200 字节（1 字节/格）改成 2400 字节（每格 2 字节） - 变量地址按新 ELF 更新（g_state 0x7AC、mine_bm 0x86C、g_ncells 0x8B4 ...） - 已揭开格数直接读 opened_cnt（0x7B4），通关目标改成 g_ncells - g_mines fb2png.py： - 支持每格 2 字节（byte0 字形[5:0] / byte1 颜色[2:0]） - 字库不再手工抄表，改成直接解析 cpu21_vga.v 的 font_row()，RTL 加字模会自动跟随 - 字形 16..41 显示成 A-Z play_saolei.tcl： - 用绝对路径找系统 Python：xsim 的环境里 py 会选中 Vivado 自带的 python3.8，报 SRE module mismatch - 清掉 PYTHONHOME/PYTHONPATH，否则系统 python 也会去 Vivado 的 lib 找模块 - render/save_shot 补 global python 实测：hard 模式 30x16 棋盘在终端正常显示，点击展开的区域横跨屏幕第 13~22 行（含中线以下的 8 行）-> 证实 FB_WORDS 那个"只能写前 15 行"的 bug 已修好	2026-09-23 21:21:32 +08:00
Alpha	10d4836ad7	fix(saolei): 修 hard 模式光标到某一格就跳回最左边（列只有 5 位）现象：只看 hard 模式时，光标移到某一排的某个格子后再往右，会跳回最左边。原因：光标的列字段只有 5 位。 - 软件 update_cursor_reg()：REG_CURSOR = (cur_c & 31u) \| ... - RTL cpu21_vga.v：cursor_here = (cursor_i[4:0] == ccol) && ... hard 棋盘宽 30、左上角列 5，光标列能到 35，35 被掩成 3，于是画在第 3 列。初级/中级列最大 25 以内，所以只有 hard 暴露出来；背景界面光标能走到列 39，同样受影响。改法： - saolei.c：列掩码 31u -> 63u（6 位，覆盖 0..39） - cpu21_vga.v：cursor_i[4:0] -> cursor_i[5:0]	2026-09-23 21:13:35 +08:00
Alpha	7e13571744	fix(saolei): 修显示/难度/数字三处问题（只本地提交） 1) 显示：VGA 的像素色 = 字模点 ? 字符色 : 背景色，而背景是黑的，所以 START 按钮上那几个 C_BLACK 字母的字形点和空白处全黑，整格看不见。改成黄色。 2) 难度：三档改成微软扫雷的真实尺寸 9x9/10、16x16/40、30x16/99（原来三档都是 16x16，只有雷数不同）。棋盘尺寸由编译期常量改成运行期变量 (g_bw/g_bh/g_board_r0/g_board_c0)，所有索引改用 mul/divu/remu（这颗核都有），棋盘自动居中；BFS 加 seen_bm 去重，避免重复入队把队列撑满丢格。 3) RTL：cpu21_riscv_redirect_int_bpb 例化 cpu21_mmio 时漏传 FB_WORDS，mmio 用默认 300，fb_ok 把显存写卡在前 300 字（前 15 行），屏幕下半部分永远刷不出来。补上 .FB_WORDS(FB_WORDS) 并给顶层加参数，mmio 默认值也改成 600。验证： - build.ps1：编译 + check_isa 指令白名单全部通过（新增的 mul/divu/remu 都合法） - 棋盘逻辑（PC 上 gcc 跑 _tmp/logic，不改仓库）：三档 x 40 局 x 全部格子， count_adj 与独立重算逐格一致，雷数、首点 3x3 安全区都正确 -> 数字与雷位没有逻辑矛盾，看到的 3 旁边 4 个雷应是显示层问题	2026-09-23 20:54:28 +08:00