如何运行Taxi回归测试？cocotb、pytest与Verilator完整工作流解析

• 硬件开发
• 网络
• 嵌入式

Taxi 是一个用 System Verilog 编写的 AXI、AXI stream、Ethernet 与 PCIe 组件库（即 Corundum 网卡、Zircon 协议栈的底层积木），每个模块都配有完整的 cocotb 测试平台。本文带你完整走通Taxi 回归测试工作流：安装 cocotb 与 Verilator 环境、看懂测试目录结构，再掌握 pytest、tox、cocotb Makefile 三种运行方式，最后学会像 CI 一样把回归任务拆成 20 组并行执行。

环境准备：安装 cocotb 与 Verilator 依赖

Taxi 的仿真基于两大支柱：Verilator（System Verilog 仿真器）+cocotb（Python 驱动的测试平台）。运行测试前需要安装以下软件包（版本以 tox.ini 为准）：

安装 Verilator（以 Ubuntu 为例）：

sudo apt install verilator

Python 依赖可以用 pip 手动安装，也可以交给 tox 自动处理（见下文）：

pip install pytest pytest-xdist pytest-split \ cocotb cocotb-bus cocotb-test \ cocotbext-axi cocotbext-eth cocotbext-uart \ cocotbext-pcie cocotbext-i2c scapy

💡 推荐用 tox 或虚拟环境隔离依赖，避免污染系统 Python。

看懂 Taxi 测试目录结构：tb 文件夹三件套

Taxi 按功能模块组织代码（src/ 下的axi、axis、eth、dma、pcie、lss等）。以taxi_axis_fifo为例，每个测试目录都遵循统一的"三件套"结构：

src/axis/tb/taxi_axis_fifo/ ├── Makefile # cocotb make 流程：SIM、WAVES、参数配置 ├── test_taxi_axis_fifo.py # cocotb 测试 + pytest 用例（含参数矩阵） └── test_taxi_axis_fifo.sv # 仿真顶层：把 RTL 例化进 cocotb 顶层

• Makefile（如 src/axis/tb/taxi_axis_fifo/Makefile）：声明SIM ?= verilator，指定 RTL 源文件，并通过PARAM_*导出模块参数，最终 include cocotb 的Makefile.sim。
• test_xxx.py：上半部分是@cocotb.test()协程测试（发帧、收帧、断言），下半部分是 cocotb-test 的 pytest 用例，通过@pytest.mark.parametrize展开出大量参数组合（如数据位宽 8/16/32/64 × 多种 FIFO 配置），见 src/axis/tb/taxi_axis_fifo/test_taxi_axis_fifo.py。
• test_xxx.sv：仿真顶层 wrapper，将 DUT 例化其中供 cocotb 访问。

另外注意每个模块下的lib/taxi是一个指向仓库根的符号链接，用于把整个仓库的源文件纳入仿真编译路径，无需特殊处理。

三种运行回归测试的方式

Taxi 官方支持三种运行方式（README.md 中的 Testing 一节有说明），灵活选择即可：

方式一：pytest 直接运行单个测试用例

开发调试时最常用——只跑一个模块甚至一个参数组合：

# 在仓库根目录执行，只跑 taxi_axis_fifo 这一个模块 pytest src/axis/tb/taxi_axis_fifo --verbose # 用 -k 精确过滤参数组合 pytest src/axis/tb/taxi_axis_fifo --verbose -k "data_w8"

pytest 配置来自 tox.ini：testpaths = src让 pytest 递归收集src/下所有tb/测试，norecursedirs = lib则跳过符号链接的 lib 目录避免重复。每个参数组合会编译一个独立的sim_build目录并缓存，重复运行无需重新编译。

方式二：tox 一键运行完整回归

tox 会自动创建隔离的 Python 虚拟环境并装好全部依赖，然后执行pytest -n auto --verbose（-n auto由 pytest-xdist 提供，按 CPU 核数并行）：

pip install tox # 在项目根目录运行全部回归测试 tox

想覆盖默认参数（比如限制并行数），直接在后面追加即可：

tox -- -n 4 --verbose

方式三：cocotb Makefile 单独仿真一个模块

不走 pytest，直接用 make 驱动 cocotb，适合只想快速复现单个用例并查看波形的场景：

# 进入某个测试目录 cd src/axis/tb/taxi_axis_fifo # 用 Verilator 仿真（Makefile 默认 SIM=verilator） make SIM=verilator # 打开 FST 波形，便于用 GTKWave 等工具查看 make SIM=verilator WAVES=1

WAVES=1会给 Verilator 加上--trace-fst并导出波形文件；Makefile 还支持SIM=icarus等其它模拟器切换。

像 CI 一样并行：pytest-split 拆分 20 组回归

完整回归包含数百个用例（每个用例都是一次完整的 Verilator 编译+仿真），官方 CI（.github/workflows/regression-tests.yml）的策略是：把全部测试按历史耗时拆成 20 组，在 20 个并行 runner 上各跑一组。本地可以照抄这条命令（--splitting-algorithm least_duration基于仓库中的 .test_durations 耗时数据做均衡分配）：

tox -- -n auto --verbose --splits 20 --group 1 --splitting-algorithm least_duration

把--group 1换成 2~20 就是其余各组。如果你在自己的机器上跑，一般只需：

tox -- -n auto --verbose

让所有核"火力全开"即可。

常见问题与调试验招

• 首次运行很慢？正常。每个参数组合都要单独编译一份 Verilator 仿真二进制（sim_build/目录），后续重跑会命中缓存显著加速。
• 想改参数调试？直接改对应tb/*/Makefile里的PARAM_*值，或 pytest 用例里的parameters字典，再用方式三 make 单独跑。
• 想换模拟器？Makefile 通过SIM变量切换（verilator / icarus），icarus 下参数以-P形式注入，verilator 下以-G形式注入，Makefile 已自动处理。
• 产物不用提交：.gitignore已忽略sim_build、*.fst、results.xml等仿真产物。
• 贡献或学习测试写法？任意tb/目录都是完整范例，例如 src/axi/tb/taxi_axi_interconnect/ 展示了多主多从互联的测试组织方式。

按这套工作流，从单个模块的快速调试到全量回归并行验证，Taxi 的测试体系都能从容应对 🚀。

• 硬件开发
• 网络
• 嵌入式