#!/usr/bin/env python3 """把中断测试程序适配到这块 CPU 上板运行（只改 ROM 内容，不改 CPU 语义）。 背景 ---- programs/risc-v-intrupt-ccab.hex 是课程的中断/异常测试程序（270 字）。 直接放进板上 ROM 会有两个问题： 1) ISR 里的 ecall 会停机 三个中断服务程序里各有一条 "addi a7,zero,10" + "ecall"。这颗 CPU 的约定是 a7==34 的 ecall 是历史"显示"调用（无操作），其余 a7 值一律让流水线停机并等待 go_i。于是 ISR 跑到这里就卡住：后面的中断服务显示循环永远不执行，主程序的 跑马灯也停在原地。 -> 把 "addi a7,zero,10" + "ecall" 换成两条 NOP。 2) 显示刷新太快，数码管上看不出跑马灯 原来的显示是 "lui a7,1" + "sw a0,0(a7)"（写 MMIO 的 LED 寄存器）。主循环里 两次显示只隔几拍（50 MHz 下约 0.1 us），而数码管是按位动态扫描的，根本来不及 分辨，只会看到一片亮。 -> 把每条显示换成 "jal ra,DISP_DLY" + "nop"，由追加在 ROM 末尾的 DISP_DLY 完成"写 LED 寄存器 + 约 10 ms 延时"。 （注意：早先把旧的 "addi a7,zero,34 + ecall" 换成 MMIO 存储时，rs1 域算错， 把 sw 写成了 sb —— 只更新 LED 寄存器的低字节，高位一直是旧值，显示自然是 错的。DISP_DLY 内部统一用正确的 sw 写整个字，这个脚本会顺带纠正。） 3) **修正 ISR2 / ISR3 的现场恢复顺序** 原始 hex 是手工改过的，两个 ISR 的出栈顺序被写乱（ISR1 是对的）： * ISR3：把 s1 从 s3 的槽位弹出，于是 s1 被写成 s3 保存的值 0xFFFFF111； ISR3 返回后，正在跑 BLT 测试的 ISR2 的循环计数 s1 就变成了 -3823， 循环要跑 3800 多次（约 170 万周期）才退出 —— 看起来就是“二级中断返回 之后卡住”； * ISR2：s0/s2/a0/a7/s1/t3/t1 全部错位，返回后调用者的这些寄存器被破坏。 -> 按 asm 清单里正确的 LIFO 顺序，只改 12 条 `lw` 的目标寄存器（字数不变、 地址不动），ISR3 改 5 条、ISR2 改 7 条。 5) **修正 ISR3 的 SB 测试用到的未保存寄存器** ISR3 的现场只保存了 s1/a7/a0/s0/s3/s4/s5/s6/uepc，但它的 SB 测试却用 t1（地址）、t3（计数）、s2（增量）—— 这三个都没保存。后果： * 若 IRQ3 抢占正在跑 DIVU 测试的 ISR1（ISR1 用 t3 做递减计数），ISR1 的 计数会被 ISR3 改成 0；ISR1 恢复后 `addi t3,t3,-1` 得到 -1，`bne t3,zero` 永远成立 —— ISR1 的 DIVU 循环再也出不来，表现为“三级中断之后卡住”； * 主程序的跑马灯步长 t1 也会被改掉。 -> 改用 ISR3 自己保存的 s4/s5/s6：SB 测试结束后紧接着的 IntLoop3 （0x3B4 起）会重新给它们赋值，所以这样换是安全的；同样只改寄存器域， 字数与地址不变。 6) **ISR 不能破坏被打断代码的 ra** 三个 ISR 的现场里都保存了 s1/a7/a0/s0/s3/s4/s5/s6（外加各自的测试寄存器）， 但**都没有保存 ra**，而它们要调用显示例程，`jal ra,DISP_DLY` 会把 ra 写成 ISR 内部的返回地址。后果：如果中断恰好落在被打断代码依赖 ra 的位置 —— 典型就是主程序正停在 DISP_DLY 末尾的 `jalr zero,0(ra)`（第 0x454 字） —— 中断返回后 `jalr` 会跳到 ra 里的地址，也就是 ISR 内部的某条指令上， 于是一路执行到 ISR 结尾的 `csrrci zero,0x4,1`，把 MIE 永久清零： “跑一阵子之后拨开关再也不响应，只能按复位”。窗口只有 1~2 拍，所以平时 很难遇到（仿真里把延时改到极小才会碰上）。 -> 给 ISR 另加一份显示例程 DISP_DLY_ISR（0x458），链接寄存器改用 **a0**， 显示值改走 **a7**：这两个寄存器三个 ISR 都保存/恢复，所以 * ISR 完全不碰 ra，被打断的代码停在 DISP_DLY 哪里都安全； * ISR 自己被内层中断打断时，内层 ISR 返回也会把 a0/a7 恢复成被打断时 的值，所以 DISP_DLY_ISR 自己的 `jalr zero,0(a0)` 同样安全。 主程序的 3 个显示点仍用原来的 DISP_DLY（链接在 ra，行为不变）。 每个 ISR 显示点：`jal ra,DISP_DLY` + `nop` 换成 `add a7,a0,zero` + `jal a0,DISP_DLY_ISR` —— 仍是 2 字换 2 字。 以上替换都是 **2 字换 2 字**，两个例程又追加在最后一条指令（uret）之后，所以 **所有指令地址都保持不变**，三个中断入口仍然是 0x0AC / 0x1E4 / 0x308。 DISP_DLY（8 字，追加在程序末尾） -------------------------------- sw ra, 256(sp) # 保存返回地址 lui a7, 1 # a7 = 0x1000 = LED_ADDR sw a0, 0(a7) # 把 a0 写进 LED 寄存器（数码管显示它的 8 位十六进制） lui t2, DELAY # 计数初值为负，向上数到 0（约 10 ms @50 MHz） 1: addi t2, t2, 1 blt t2, zero, 1b lw ra, 256(sp) jalr zero, ra, 0 为什么返回地址存在 sp+256 而不是程序栈里： 本程序的 ISR 是“先把 sp 加上去，再往里存”的向上增长栈，一层最多占 48 字节， 最多嵌套 4 层（IRQ_STACK_DEPTH=4）共 192 字节，所以 [sp, sp+192) 是中断随时 可能写到的区域。把返回地址放在 sp+256（越过了这个区域）： * 从 ISR 里调用时，不会覆盖 ISR 存好的 s6 / uepc（早期用 sp-8 就是这么坏掉的： uepc 被写坏后 uret 会返回到 ISR 内部地址，最后执行到 csrrci 把 MIE 永久清零）； * 中断（包括多层嵌套）随时打断延时也不会破坏它，因为嵌套 ISR 只会在 [sp, sp+192) 里压栈； * 每次调用各用自己 sp+256 的位置，所以嵌套调用也互不影响。 延时计数不用“递减到 0”而用“负数向上数到 0”：万一被嵌套调用改掉了 t2，循环也 只会在 t2 >= 0 时立即退出，不会像递减写法那样绕成 40 亿次而死等。 用法 ---- python tools/adapt_intrupt_ccab.py <输入.hex> <输出.vh> [输出_fast.hex] <输入.hex> programs/risc-v-intrupt-ccab.hex（未适配的原始镜像） <输出.vh> srcs/board/risc-v-intrupt-ccab.vh（上板综合用） [输出_fast.hex] 可选：延时改成约 0.6 us 的仿真专用版本。上板一次中断服务要跑 几十毫秒（几十万个时钟），仿真跑完整流程会很慢，因此仿真用这个 快版来验证控制流（入口 / 中断返回 / 不停机），延时量本身不影响 控制流。 """ import sys NOP = 0x00000013 LED_ADDR_HI = 1 # lui a7, 1 -> a7 = 0x1000（LED_ADDR） # 延时计数：计数初值为负，向上数到 0。0xFFFC0000 -> 0x40000 = 262144 次 # （每轮约 2 个时钟）= 52.4 万个时钟 ≈ 10 ms @50 MHz。 DELAY_NEG_HI = 0xFFFC0 DELAY_FAST_NEG = -16 # 仿真用：addi t2, zero, -16 ≈ 0.6 us # DISP_DLY 保存返回地址的偏移：必须大于 ISR 最大嵌套栈用量（4 层 x 48B = 192B） LINK_SLOT = 256 # 寄存器号 ZERO, RA, SP, GP, T2, A0, A7 = 0, 1, 2, 3, 7, 10, 17 def enc_i(imm, rs1, f3, rd, op=0x13): return ((imm & 0xFFF) << 20) | (rs1 << 15) | (f3 << 12) | (rd << 7) | op def enc_s(imm, rs2, rs1, f3): imm &= 0xFFF return (((imm >> 5) << 25) | (rs2 << 20) | (rs1 << 15) | (f3 << 12) | ((imm & 0x1F) << 7) | 0x23) def enc_b(imm, rs2, rs1, f3): imm &= 0x1FFF return ((((imm >> 12) & 1) << 31) | (((imm >> 5) & 0x3F) << 25) | (rs2 << 20) | (rs1 << 15) | (f3 << 12) | (((imm >> 1) & 0xF) << 8) | (((imm >> 11) & 1) << 7) | 0x63) def enc_u(imm, rd): return ((imm & 0xFFFFF) << 12) | (rd << 7) | 0x37 def enc_j(imm, rd): imm &= 0x1FFFFF return ((((imm >> 20) & 1) << 31) | (((imm >> 1) & 0x3FF) << 21) | (((imm >> 11) & 1) << 20) | (((imm >> 12) & 0xFF) << 12) | (rd << 7) | 0x6F) HALT_LOAD = enc_i(10, ZERO, 0, A7) # addi a7, zero, 10 ECALL = 0x00000073 DISP_LUI = enc_u(LED_ADDR_HI, A7) # lui a7, 1 DISP_SW = enc_s(0, A0, A7, 2) # sw a0, 0(a7) <- 正确：字写 DISP_SB_BAD = enc_s(0, A0, A7, 0) # sb a0, 0(a7) <- 误写成字节写，一并修正 # 说明：这两种都当成"显示点"。DISP_DLY 内部一律用正确的 sw 写整个字，因此即使 # 输入镜像里是 sb（只写低字节，显示的高位会残留旧值），适配后也会恢复正常。 def disp_dly(delay_word): """DISP_DLY 的 8 条指令（delay_word 决定延时长短）。 返回地址存在 sp+LINK_SLOT，位于 ISR 可能压栈的区域之上，所以中断（含嵌套） 打断延时也不会破坏它 —— 见文件头的说明。 """ return [ enc_s(LINK_SLOT, RA, SP, 2), # sw ra, 256(sp) DISP_LUI, # lui a7, 1 DISP_SW, # sw a0, 0(a7) delay_word, # lui t2, 0xFFFC0 / addi t2, zero, -16 enc_i(1, T2, 0, T2), # addi t2, t2, 1 enc_b(-4, ZERO, T2, 4), # blt t2, zero, -4 enc_i(LINK_SLOT, SP, 2, RA, 0x03), # lw ra, 256(sp) enc_i(0, RA, 0, ZERO, 0x67), # jalr zero, ra, 0 ] def disp_dly_isr(delay_word): """ISR 专用的显示/延时例程（8 条）—— 链接寄存器用 a0，不用 ra。 三个 ISR 的现场都保存了 a7 与 a0（s1/a7/a0/s0/s3/s4/s5/s6），所以把链接放 a0、把显示值放 a7 不会额外破坏任何东西；而 ra 完全不被触碰，被打断的代码 即使停在主 DISP_DLY 的 `jalr zero,0(ra)` 上也不会被破坏。 """ return [ enc_s(LINK_SLOT, A0, SP, 2), # sw a0, 256(sp) 保存链接寄存器 enc_u(LED_ADDR_HI, A0), # lui a0, 1 a0 = 0x1000 enc_s(0, A7, A0, 2), # sw a7, 0(a0) 显示 a7 delay_word, # lui t2, 0xFFFC0 / addi t2,zero,-16 enc_i(1, T2, 0, T2), # addi t2, t2, 1 enc_b(-4, ZERO, T2, 4), # blt t2, zero, -4 enc_i(LINK_SLOT, SP, 2, A0, 0x03), # lw a0, 256(sp) enc_i(0, A0, 0, ZERO, 0x67), # jalr zero, a0, 0 ] # 三个中断入口的原指令（核对地址没有跑偏） ISR_ENTRY = {43: 0x00512023, 121: 0x00612023, 194: 0x00912023} # 三个 ISR 的代码从 ISR1 入口开始一直排到程序末尾（主程序在它之前） ISR1_WORD = min(ISR_ENTRY) # 需要修正目标寄存器的 `lw X,0(sp)`：addr -> (当前错误的 rd, 正确的 rd) # ISR3（入口 0x308）恢复顺序应为：uepc,s6,s5,s4,s3,s0,a0,a7,s1 # ISR2（入口 0x1E4）恢复顺序应为：uepc,s6,s5,s4,s3,s0,a0,a7,s2,s1,t3,t1 FIX_POPS = { 0x410: (9, 19), 0x418: (19, 8), 0x420: (8, 10), 0x428: (10, 17), 0x430: (17, 9), # ISR3 0x2D0: (18, 8), 0x2D8: (9, 10), 0x2E0: (28, 17), 0x2E8: (6, 18), 0x2F0: (8, 9), 0x2F8: (10, 28), 0x300: (17, 6), # ISR2 } # ISR3 的 SB 测试用了未保存的 t1/t3/s2 -> 改成 ISR3 自己保存的 s4/s5/s6 # addr -> (要改的域, 原寄存器号, 新寄存器号) T1, T3, S2, S4, S5, S6 = 6, 28, 18, 20, 21, 22 FIX_ISR3_SB = { 0x358: ('rd', T1, S4), 0x35C: ('rd', T3, S5), 0x364: ('rd', S2, S6), 0x368: ('rs1', T1, S4), 0x378: ('rs2', S2, S6), 0x37C: ('rd_rs1', T1, S4), 0x380: ('rd_rs1', T3, S5), 0x384: ('rs1', T3, S5), 0x388: ('rd', T3, S5), 0x38C: ('rd', T1, S4), 0x390: ('rs1', T1, S4), 0x3A0: ('rd_rs1', T1, S4), 0x3A4: ('rd_rs1', T3, S5), 0x3A8: ('rs1', T3, S5), } def read_hex(path): words = [] with open(path, encoding="ascii") as f: for line in f: line = line.split("//")[0].strip() if line: words.append(int(line, 16)) return words def patch(words): """返回 (适配后的字表, 适配后的快版字表, 统计信息)。""" halt_sites = [i for i in range(len(words) - 1) if words[i] == HALT_LOAD and words[i + 1] == ECALL] if len(halt_sites) != 3: raise SystemExit("预期 3 处 'addi a7,zero,10 + ecall'（ISR 停机点），" "实际找到 %d 处；输入文件不是预期的原始镜像？" % len(halt_sites)) disp_sites = [i for i in range(len(words) - 1) if words[i] == DISP_LUI and words[i + 1] in (DISP_SW, DISP_SB_BAD)] if len(disp_sites) != 11: raise SystemExit("预期 11 处 'lui a7,1 + sw/sb a0,0(a7)'（显示点），" "实际找到 %d 处；输入文件不是预期的原始镜像？" % len(disp_sites)) bad_store = [i for i in disp_sites if words[i + 1] == DISP_SB_BAD] for i in halt_sites: words[i] = NOP words[i + 1] = NOP # plain 变体：只去掉停机 ecall，显示保持原来的 "lui + sw" 两字写法 # （必须在把显示点改成 jal 之前取副本，否则会生成“跳到没有函数体的地址”的镜像） plain = list(words) # DISP_DLY 紧跟在原程序的最后一条指令之后（原程序长度不变） disp_pc = 4 * len(words) isr_pc = disp_pc + 32 # ISR 专用的 DISP_DLY_ISR 再占 8 字 isr_sites = [] for i in disp_sites: if i >= ISR1_WORD: # 三个 ISR 里的显示点：改用 a0 做链接寄存器、显示值走 a7 # 注意 jal 落在显示点的后一条（i+1）上，偏移要相对它自己算 isr_sites.append(i) words[i] = enc_i(0, A0, 0, A7) # add a7, a0, zero words[i + 1] = enc_j(isr_pc - 4 * (i + 1), A0) # jal a0, DISP_DLY_ISR else: # 主程序里的显示点：照旧用 ra 链接 words[i] = enc_j(disp_pc - 4 * i, RA) words[i + 1] = NOP if not isr_sites: raise SystemExit("没有找到 ISR 里的显示点；中断入口地址对不上？") # 自检：把刚写进去的 jal 偏移反解出来，确认真的跳到两个例程的入口 def jal_target(w, pc): imm = (((w >> 31) & 1) << 20) | (((w >> 21) & 0x3FF) << 1) \ | (((w >> 20) & 1) << 11) | (((w >> 12) & 0xFF) << 12) if imm & 0x100000: imm -= 0x200000 return pc + imm for i in disp_sites: if i >= ISR1_WORD: want, at = isr_pc, 4 * (i + 1) # ISR：jal 在显示点后一条 else: want, at = disp_pc, 4 * i # 主程序：jal 就在显示点上 got = jal_target(words[at // 4], at) if got != want: raise SystemExit("显示点 0x%03X 的跳转目标算错了：0x%03X != 0x%03X" % (4 * i, got, want)) for idx, want in ISR_ENTRY.items(): if words[idx] != want: raise SystemExit("中断入口 0x%03X 处的指令被改动了（%08X != %08X）" % (4 * idx, words[idx], want)) # --- 4) 修正 ISR2 / ISR3 的现场恢复顺序（只改 lw 的 rd 域） --- fixed_pops = 0 for pc, (bad_rd, rd) in FIX_POPS.items(): w = words[pc // 4] op, f3 = w & 0x7F, (w >> 12) & 7 rs1, imm = (w >> 15) & 0x1F, (w >> 20) & 0xFFF old_rd = (w >> 7) & 0x1F if not (op == 0x03 and f3 == 2 and rs1 == SP and imm == 0): raise SystemExit("0x%03X 不是预期的 `lw X,0(sp)`（%08X）" % (pc, w)) if old_rd == rd: continue # 已经是对的（重复运行时跳过） if old_rd != bad_rd: raise SystemExit("0x%03X 的目标寄存器不是预期的 %d（实际 %d）" % (pc, bad_rd, old_rd)) words[pc // 4] = (w & ~(0x1F << 7)) | (rd << 7) fixed_pops += 1 # --- 5) 把 ISR3 SB 测试里的 t1/t3/s2 换成 s4/s5/s6 --- def set_field(w, name, val): if name == 'rd': return (w & ~(0x1F << 7)) | (val << 7) if name == 'rs1': return (w & ~(0x1F << 15)) | (val << 15) if name == 'rs2': return (w & ~(0x1F << 20)) | (val << 20) if name == 'rd_rs1': return ((w & ~(0x1F << 7)) | (val << 7)) & ~(0x1F << 15) | (val << 15) raise SystemExit('未知域 ' + name) fixed_sb = 0 for pc, (field, old, new) in FIX_ISR3_SB.items(): w = words[pc // 4] idx = {'rd': (w >> 7) & 0x1F, 'rs1': (w >> 15) & 0x1F, 'rs2': (w >> 20) & 0x1F} if field == 'rd_rs1': cur = idx['rd'] if idx['rs1'] != cur: raise SystemExit('0x%03X 的 rd/rs1 不一致' % pc) else: cur = idx[field] if cur == new: continue # 已经改过了 if cur != old: raise SystemExit('0x%03X 的 %s 不是预期的 %d（实际 %d）' % (pc, field, old, cur)) words[pc // 4] = set_field(w, field, new) fixed_sb += 1 slow = disp_dly(enc_u(DELAY_NEG_HI, T2)) + disp_dly_isr(enc_u(DELAY_NEG_HI, T2)) fast = disp_dly(enc_i(DELAY_FAST_NEG, ZERO, 0, T2)) \ + disp_dly_isr(enc_i(DELAY_FAST_NEG, ZERO, 0, T2)) return (words + slow, words + fast, plain, (halt_sites, disp_sites, disp_pc, [i for i in disp_sites if i < ISR1_WORD], isr_sites, bad_store, fixed_pops, fixed_sb)) def write_hex(path, words): with open(path, "w", encoding="ascii", newline="\n") as f: for w in words: f.write("%08X\n" % w) def write_vh(path, words, src_name, total, note): with open(path, "w", encoding="utf-8", newline="\n") as f: f.write(" // 由 tools/adapt_intrupt_ccab.py 生成 —— 不要手改\n") f.write(" // source: %s（%d 字，其余地址填 NOP）\n" % (src_name, len(words))) f.write(" // %s\n" % note) for addr in range(total): w = words[addr] if addr < len(words) else NOP f.write(" rom[%d] = 32'h%08X;\n" % (addr, w)) def main(): if len(sys.argv) < 3: raise SystemExit(__doc__.strip().split("用法")[-1]) src, dst_vh = sys.argv[1], sys.argv[2] dst_fast = sys.argv[3] if len(sys.argv) > 3 else None dst_plain = sys.argv[4] if len(sys.argv) > 4 else None words = read_hex(src) slow, fast, plain, (halt_sites, disp_sites, disp_pc, main_sites, isr_sites, bad_store, fixed_pops, fixed_sb) = patch(words) total = 1024 write_vh(dst_vh, slow, src, total, "已适配：去掉 ISR 停机 ecall、显示改为 MMIO+DISP_DLY（约 10 ms）") if dst_fast: write_hex(dst_fast, fast) if dst_plain: write_hex(dst_plain, plain) print("适配完成：%s（原程序 %d 字 + DISP_DLY %d 字 = %d 字）" % (dst_vh, len(words), len(slow) - len(words), len(slow))) print(" 去掉的停机 ecall 位置：%s" % ", ".join("0x%03X" % (4 * i) for i in halt_sites)) print(" 换成显示调用的点：主程序 %s｜ISR %s" % (", ".join("0x%03X" % (4 * i) for i in main_sites), ", ".join("0x%03X" % (4 * i) for i in isr_sites))) print(" DISP_DLY 本体：0x%03X - 0x%03X（主程序用，链接在 ra）" % (disp_pc, disp_pc + 28)) print(" DISP_DLY_ISR 本体：0x%03X - 0x%03X（ISR 用，链接在 a0，不碰 ra）" % (disp_pc + 32, disp_pc + 60)) print(" 修正的现场恢复顺序：%d 条" % fixed_pops) print(" ISR3 SB 测试改用的已保存寄存器：%d 条" % fixed_sb) if bad_store: print(" 顺带修正的字节写显示：%s" % ", ".join("0x%03X" % (4 * i) for i in bad_store)) print(" 中断入口（不变）：0x0AC / 0x1E4 / 0x308") if dst_fast: print(" 仿真快版：%s（延时约 0.6 us）" % dst_fast) main()