RISC-V的CPU验证在国内高校和企业里越来越常见，很多同学拿着设计好的处理器核，跑程序也能跑通几个，但真到了流片或者上板卡之前，心里其实是没底的。你说你的ALU没问题、分支跳转也正常，可一跑复杂的CoreMark或者Linux，就各种取指错乱、写回数据不对。问题到底出在哪？大概率是基础指令集里某个边界情况你没测到。这就是我今天想聊的riscv-tests——一个看起来简单、实际上是把ISA全覆盖的验证工具集，适合在CPU设计前期快速把指令正确性兜住。
riscv-tests是RISC-V官方的指令集测试集，配合RISC-V GNU工具链，能够在纯仿真环境下对你的CPU设计做比较完整的ISA一致性验证。它的核心价值在于：不需要你写复杂的testbench，不需要搭建太完备的SoC环境，就能把RV32I、RV64I、乘除法扩展M、原子操作A等指令逐条验证到位。适合刚写完RTL、想快速定位指令实现bug的开发者，也适合高校做单总线CPU设计、多周期MIPS转RISC-V实验、或者用Logisim做CPU仿真验证的场景。
1. 验证CPU之前，先搞清楚你为什么需要riscv-tests
1.1 CPU设计里最容易翻车的地方
我见过太多同学写RTL的时候，代码写得行云流水，一上仿真就崩。崩的位置往往还不是那种特别复杂的指令，而是最基础最容易被忽略的那几条。比如LUI和AUIPC的高位立即数拼接、分支指令的符号扩展、移位指令的边界count、Load/Store的对齐异常。这些指令看起来一个周期就能跑完，但一旦实现细节处理错，整个程序跑飞了你都找不到原因。
还有一个很典型的问题：很多人验证自己的CPU时，喜欢直接用编译好的裸机程序或者直接怼一个Hello World上去跑。这么做有一个致命盲区——编译器通常只会生成程序里用到的那部分指令。你的程序不涉及乘法、不涉及无符号比较、不涉及某些异常路径，那CPU里面对应的硬件逻辑就一直是坏的，只是你自己不知道。等到后面移植操作系统或者跑复杂应用的时候，这些隐藏的bug会一次性爆发出来，排查起来极其痛苦。
1.2 riscv-tests能帮你把验证变成一条流水线
riscv-tests做的事情其实特别朴素：把RISC-V指令集里每一条指令、每一个关键标志位的行为都写成独立的小测试程序，每个程序只测一个点。编译之后生成一个可执行文件，你的CPU把它跑完，最后对比通用寄存器的值或者签名区（signature）的内容，就知道这一条指令实现得对不对。
这套东西的好处在于：
- 测试粒度细到单条指令，你能根据报错信息直接定位到是哪个指令没写对，不用猜。
- 不只测正向结果，还测了很多边界情况，比如移位量为32、分支偏移为负数、减法借位等。
- 它的测试环境很简单，不需要完整的SoC，串口、中断、外设统统不需要，你只要能把指令取进来、执行完、把结果写回，就可以了。
所以对做CPU设计的人来讲，riscv-tests就是你给自己CPU做的“科目一考试”——题目全是固定的，你只需要保证自己别挂科。
2. 先把riscv-tests的目录结构和构建流程吃透
2.1 源码获取和工具链准备
riscv-tests的源码托管在GitHub上，标准的clone方式就能拿到：
git clone https://github.com/riscv-software-src/riscv-tests.git拿到源码之后，你还得准备RISC-V交叉编译工具链。这一步建议直接用官方的预编译工具链，或者自己编译riscv-gnu-toolchain。工具链的安装路径要提前规划好，因为后面编译测试集的时候会用到RISCV环境变量来指定工具链的位置。
export RISCV=/opt/riscv export PATH=$RISCV/bin:$PATH同时还需要设备树编译器dtc。如果你是基于Ubuntu环境，执行：
sudo apt-get install device-tree-compiler这里有一个容易被新手忽略的点：riscv-tests的Makefile默认假设你的工具链前缀是riscv64-unknown-elf-，如果你的工具链前缀不同，编译会直接报错找不到编译器。可以用环境变量RISCV_PREFIX覆盖，比如32位工具链就设置成riscv32-unknown-elf-。
2.2 从Makefile看懂整个验证框架
记得把整个仓库克隆下来后，先别急着编译，花10分钟把根目录的Makefile浏览一遍。riscv-tests的设计思路是：每一类测试对应一个子目录，用make参数来控制编译哪一组。
make isa # 编译全部ISA测试 make rv32ui-p-addi # 编译单条指令测试 make rv64um-p-mul # 编译64位乘除法测试 make benchmarks # 编译benchmark测试编译出来的文件有几种格式：.elf是标准的可执行文件，.dump是反汇编文件（排查指令执行问题时特别有用），还有一些.hex或者.bin需要你根据Makefile规则手动生成，用来加载到仿真ROM里。
这里解释一下为啥要重点看Makefile。因为你之后要把测试加载进自己的仿真环境，可能并不走它默认的编译流程，而是想直接生成一个纯二进制镜像，或者按你的存储器宽度拆分成多个hex文件。搞清楚Makefile的组织方式，你就能写出自己的转换脚本，事半功倍。
2.3 测试的三个层级：ISA测试、基准测试、微基准测试
riscv-tests仓库里大致有三类内容：
第一类是isa目录下的指令集测试，这是核心，每条指令一个或者几个测试文件，覆盖了基本整数指令、乘除指令、原子操作指令、浮点指令等。这类测试直接检测指令的功能正确性，不需要操作系统支持。
第二类是benchmarks目录下的基准测试，包括dhrystone、coremark、qsort等算法类程序，跑的是综合性能，同时也能验证你的CPU能不能比较流畅地跑完一段复杂的完整程序。
第三类是mt和micro相关的测试，涉及机器模式、异常处理、中断等更底层的机制，适合后面做操作系统启动、搭建完整SoC之后再验证。
对于刚开始验证CPU设计的人，我建议先把isa这组测试跑通，这是底线。跑通了ISA测试，你就有把握说自己的CPU“指令集层面对了”。之后再接benchmarks，衡量性能，最后再碰中断和异常。
3. ISA测试用例到底长什么样：以RV32UI为例
3.1 读懂一个指令测试文件的结构
打开isa/rv32ui-p-addi.S这个文件，你会看到它的结构其实很有规律。最开头是宏包含，把riscv_test.h和test_macros.h引进来，接着定义测试名称和RVTEST_RV32U这样的宏，来表示这是RV32用户模式的测试。
整个测试的核心是一个个TEST_IMM_OP或TEST_RR_OP宏的调用。比如ADD指令的测试宏：
TEST_RR_OP(2, add, 0x00000000, 0x00000000, 0x00000000 ); TEST_RR_OP(3, add, 0x00000002, 0x00000001, 0x00000001 ); TEST_RR_OP(4, add, 0x0000000a, 0x00000006, 0x00000004 );这个宏会做几件事：把两个源操作数加载到寄存器，执行目标指令，然后把结果和期望值进行比较，如果相等就继续下一条，不相等就跳转到失败处理流程。TEST_RR_OP的参数依次是测试编号、指令助记符、期望结果、源操作数1、源操作数2。
这种设计对你调试极其友好。因为如果某一条测试失败，你从仿真波形或者打印信息里能看到测试编号，就能对着源文件找到具体是哪个操作数组合触发了失败。定位问题的时间会从小时级缩短到分钟级。
3.2 签名（signature）机制：测试结果是怎么交到你手里的
riscv-tests里有一个很有意思的机制叫signature（签名）。很多测试程序并不是简单地通过就跳转到一个成功循环，而是把计算结果写入一段固定的内存区域。测试完成后，你把这部分内存内容导出来，和预先生成的.signature文件做对比，一致就是通过。
这种设计解决了一个实际问题：在纯RTL仿真里，你怎么知道程序执行成功还是失败？你可以选择让CPU执行到某个魔法地址，比如成功跳转到0xdeadbeef，但这需要你的仿真环境配合。签名机制更通用，不管你的仿真平台怎么搭，只要能在测试结束后把内存区域的数据读出来，就能判断结果。
举个例子，如果你用Verilog做仿真，可以在CPU执行到测试程序的结束点后，用$readmemh把signature区的内容导出成文本，然后和编译生成的.signature文件做diff。我之前遇到过一堆“CPU跑测试半天没反应”的情况，最后发现是CPU根本没走到测试结束点，而是在中间某条指令上卡死了。这种时候配合dump文件看PC跳转轨迹，比单纯看内部信号高效得多。
3.3 每条指令测试里藏着的边界条件
ISA测试不是简单地拿两个随机数算一下结果对不对，它覆盖了很多意想不到的边界情况。比如移位指令，测试里会把移位量设为0、1、31、32这些值，检查硬件有没有正确地按低5位取移位量。再比如分支指令，测试里会设计offset使目标地址恰好落在指令编码的边界上，看看符号扩展是否出错。
我在自己设计CPU的时候就吃过这个亏。当时的移位器只实现了shift_amount >= width时返回0，忘了验证shift_amount是从源寄存器低5位取还是全32位都参与移位。结果跑rv32ui-p-sll测试的时候，有两条测试用例直接失败。如果我只用几个手写程序验证，这种bug在正常程序里根本触发不了，因为正常的C语言编译器生成的移位操作，移位量都在合法范围内。
所以ISA测试真正有价值的不是让你测100条指令，而是它在一百多条指令里织了一张边界条件的网，帮你在早期就把硬件实现的细微错误揪出来。
4. 把riscv-tests接入你的CPU设计：从编译到上机验证
4.1 根据你的CPU是RV32还是RV64来选择测试集
在动手编译之前，先想清楚你有哪种CPU核心。它们的区别不只是寄存器和数据位宽，指令编码在低两位、控制状态寄存器地址空间、甚至部分指令的行为都有差异。所以：
- RV32I的CPU，编译
rv32ui-p-*一组的测试。 - RV64I的CPU，编译
rv64ui-p-*和rv64uc-p-*等64位特有测试。 - 如果实现了M扩展，还要加
rv32um-p-*或rv64um-p-*。 - 如果实现了A扩展（原子操作），对应的是
rv32ua-p-*。
这个选择直接决定了你后续仿真时加载的指令流宽度和存储空间大小，别混着来。尤其是RV64的测试集，指令里有些64位立即数拼接，32位CPU强行去跑大概率会在取指阶段就跑飞。
4.2 手动编译单个ISA测试并生成仿真用镜像
如果你只想快速验证一条指令，走整个make流程有点重。我通常的做法是直接进到isa目录，手动调用编译器生成需要的ELF，再转成hex或bin。
cd riscv-tests/isa riscv64-unknown-elf-gcc -march=rv64im -mabi=lp64 -static \ -I../env/p -I../macros -T../env/p/link.ld \ rv64ui-p-add.S -o rv64ui-p-add.elf riscv64-unknown-elf-objcopy -O binary \ rv64ui-p-add.elf rv64ui-p-add.bin如果仿真环境的ROM是32位宽度，你还需要把bin文件按字切分：
xxd -p -c 8 rv64ui-p-add.bin | awk '{print "32'h"$1}' > rv64ui-p-add.hex注意每个仿真环境对hex格式的要求不一样，比如Vivado的Block Memory Generator、Verilog的$readmemh、Logisim的ROM加载格式，处理起来略有差异。你自己封装一个小脚本就行。
4.3 写一个极简testbench来跑通整个流程
当你有了测试镜像之后，接下来要解决的便是怎么把它喂给你的CPU。最简单的方式是写一个testbench，初始化ROM后让CPU跑起来，再设置一个超时机制，防止测试卡死在死循环里。
我之前用的一个极简测试框架是这样的思路：
- CPU的主存映射里有一段ROM区域，测试程序编译时直接链接到这个基地址。
- testbench在仿真时间0时用
$readmemh把hex文件加载进ROM。 - CPU从固定地址开始取指执行。
- 当PC跳到测试程序的成功地址时，置一个pass信号，失败地址则置fail信号。
- 设置一个比较大的超时时钟数，超时还没出结果就直接判定失败，避免仿真挂死。
这套框架的好处是跟CPU内部微架构完全解耦，无论你是单周期、多周期、流水线还是单总线CPU，只要能按地址取指执行，就能跑这套验证。很多学校的单总线CPU设计实验、Logisim仿真验证，其实完全可以参考这种做法，只不过把testbench换成Logisim里的时钟和存储器配置。
4.4 跑通之后怎么确认每条指令都过了
riscv-tests没有提供一个统一的“全过/失败”总结，你的仿真环境需要自己把每个用例的结果汇总起来。比较省事的做法是自己写一个批量脚本：
cd riscv-tests/isa for f in rv64ui-p-*.S; do make ${f%.S}.elf # 用你自己的仿真脚本跑这个elf # 检查pass/fail信号 done跑完之后把pass的列表和fail的列表列出来。一般fail的数量不会是0，但这时候不用慌，一条一条对着反汇编dump文件看。很多fail指令其实不是你CPU逻辑错了，而是编译选项或者链接脚本没配对，比如某个寄存器被初始化成了非零值，导致测试宏的期望值对不上。
5. 实测中常见的坑：问题排查与实用技巧
5.1 编译失败：工具链prefix不对或链接脚本缺失
最典型的报错是找不到riscv64-unknown-elf-gcc或者链接时提示cannot find -lgcc。前者说明你工具链没装对或者环境变量没生效，后者往往是因为链接脚本没指定库路径。
建议直接看Makefile里的默认配置，如果你用的是本地编译的riscv-gnu-toolchain，并且默认prefix是riscv64-unknown-elf-，那基本不会出问题。但如果你用的是别人打包好的工具链，prefix可能是riscv64-unknown-linux-gnu-，这时候不设RISCV_PREFIX，编译必挂。
还有一类问题是env/p/link.ld路径不对。riscv-tests对不同运行环境有不同的链接脚本，env/p表示物理内存模式（Physical Memory），也就是裸机直接跑在物理地址上。如果你用的是env/v（虚拟内存模式），需要操作系统的支持，不适合直接用。
5.2 CPU跑测试卡死：先看是不是取指阶段就出了问题
仿真跑起来之后，最让人崩溃的现象是卡死，什么都不输出，也不触发pass/fail。这时候我的排查顺序是：
- 先看时钟复位是否正常，复位释放后PC是否跳到了ROM的起始地址。
- 再ROM里第一条指令是否被正确加载，有没有位宽不匹配的问题。比如CPU按32位取指，你却把hex文件按字节顺序装进了内存。
- 然后用波形跟踪前几条指令的执行，确认取指、译码、执行、访存、写回每个阶段都有信号翻转。
- 最后看是不是跳转指令导致PC跑飞，跑到一个没有实际存储器的地址空间去了。
有一条经验值得分享：调试卡死问题的时候，不要同时看几十个信号，先把PC、指令、写回寄存器这几个最关键的波形拉出来，跑个200个时钟周期，基本就能锁定问题范围。
5.3 测试结果全挂：先检查有没有反汇编文件对比
如果跑出的结果一直是失败，先别急着改RTL。把编译出来的.dump文件打开，仔细看测试程序的开头部分，确认第一条测试是不是从看起来合理的位置开始的。我遇到过一次很奇怪的情况，所有测试都失败，最后发现是链接脚本里内存起始地址和testbench里ROM的起始地址没对齐，导致CPU实际上从错误的位置开始执行，第一条指令就不是测试程序里的第一条。
还有一点，如果你改了工具链版本，或者改了编译选项，最好重新生成一下签名文件。riscv-tests的Makefile里make signature可以重新生成签名，但要注意编译器优化选项变了，签名也可能变。如果你自己在做寄存器流水线级实现，最好固定一套编译环境，反复用同一个版本的测试集，否则容易把环境差异当成CPU的bug来查。
5.4 善用宏开关：让调试信息变多
riscv-tests的测试宏里其实提供了一些调试选项，只是默认不开启。你可以通过-DDEBUG之类的编译选项打开更详细的寄存器打印。如果你的仿真环境支持UART输出，甚至可以直接把printf打印信息串行输出出来，这样调试体验会好很多。
不过说实话，更靠谱的调试方式还是配合仿真器的波形文件，比如VCD或FSDB。测试程序一旦失败，肯定会跳到失败分支，你在波形里定位那个跳转发生的时刻，往前回看几条指令，基本上bug点就跑不掉。
5.5 在自己的项目里写一份测试备忘录
这是我从实践里总结出来的“土办法”，但非常有效。跑通riscv-tests之后，单独维护一份备忘录，记录你验证过的指令范围、发现的问题、以及对应的波形时间点。后面如果改了流水线结构或者优化了时序，重新跑一遍测试集，再对照备忘录看看有没有新增的失败。这比每次从头排查省力得多，也方便以后接手的人快速进入状态。
6. 后续扩展：从ISA测试到更多验证手段
riscv-tests跑通，只是CPU验证马拉松的第一公里。它证明了你的指令集实现符合规范，但不代表你的CPU已经能跑操作系统、能正确处理中断、能高效执行复杂程序。后面至少要做的几件事：
可以把benchmarks搬进来，测一测真实的程序跑起来需要多少周期，算一算CPI，对处理器性能有个直观感受。如果你的CPU支持M模式，再深入看一下机器模式下的异常处理，比如mret指令、mtvec跳转等。如果再进一步，直接尝试启动一个精简的RTOS或者移植一个微型内核，那种成就感跟跑通ISA测试不是一个量级的。
不过这些都是后话。脚踏实地来说，先用riscv-tests把你的基础打牢，把那些隐藏的指令bug都揪出来，之后的每一步都会顺很多。至少在我自己的实践里，跑通rv64ui加上rv64um这两个测试组之后，再遇到系统集成阶段的问题，基本上就很少能碰到“指令执行错误”这种底层问题了。
