cocotb 入门:用 Python testbench 驱动计数器、随机激励与多 seed 回归
这是「EDA 开源工具实操」系列仿真线的第七篇。前面 iverilog 仿真入门 用 Verilog 写 testbench 驱动了一颗 4 位计数器,本篇换 cocotb 入门的主线:testbench 不再用 Verilog 写,改用 Python。被测设计还是那颗计数器(只加了一个溢出标志输出),但激励、参考模型、断言、随机种子回归全部搬进 Python——这正是 cocotb 的立身之本:验证工程师用一门真正的编程语言写 TB,而不是跟 Verilog 的 # 延时和 fork/join 较劲。
先交代 cocotb 是什么。它是一个开源的协程式验证框架:你的 Python 代码通过 VPI(Verilog Procedural Interface,仿真器对外暴露的标准 C 接口)挂进仿真器内部,Python 协程和 RTL 的 always 块在同一条仿真时间轴上交替推进。cocotb 本身不是仿真器——它不编译 Verilog、不推进波形,背后仍然站着 iverilog、Verilator 或商用仿真器。所以本篇你会看到一份奇特的 Makefile:真正的编译运行规则只有一行 include,全部来自 cocotb 官方模板。
为什么值得学?三个字:表达力。Verilog TB 里想做「随机使能 + 参考模型逐拍比对 + 失败时打出期望值和实际值」,要写一堆 reg、task 和 $display;Python 里就是一个 for 循环加两行 assert。再往后,参考模型可以直接调 Python 生态——用 numpy 算滤波器输出、用 scapy 造网络包,RTL 验证的生产力完全不是一个量级。
本文要回答的问题
- cocotb 和 iverilog 各管什么?为什么 cocotb 的 Makefile 只有一行实质内容?
- 一个 cocotb testbench 最少需要哪些零件(Clock、协程、断言)?
RisingEdge之后马上读信号为什么会读到旧值?ReadOnly解决什么问题?- 多 seed 随机回归怎么组织?一次真实 FAIL 的输出长什么样?
- cocotb 2.x 相比 1.x 有哪些会咬人的 API 变化(本篇真实踩到两个)?
一、环境:geek-eda 容器与 libpython 坑
实验跑在 Docker 容器里,本篇涉及的工具版本均为容器内实测:
- cocotb 2.1.0(
cocotb-config --version,安装在/opt/venvs/cocotb,已在 PATH) - Icarus Verilog 12.0 (stable)(
iverilog -V第一行) - Python 3.12.3、make、g++
有一个真实踩到的坑必须先说。基础镜像 geek-eda:0.1 直接跑 cocotb 会在 make 阶段就死掉:
find_libpython was not able to find a libpython in the current Python environment.
Ensure the Python development packages are installed.原因:cocotb 要把 Python 解释器嵌进仿真进程,靠的是 libpython3.12.so 这个共享库;而 0.1 镜像只装了 libpython3.12-minimal(没有 .so 本体,find / -name "libpython3.12*" 一无所获)。处置是装一个包:apt-get install -y libpython3.12,装完 find_libpython 就能定位到 /usr/lib/x86_64-linux-gnu/libpython3.12.so.1.0。本篇用这个补丁版镜像(本地 tag 为 geek-eda:0.1.1)跑全部实验——如果你本机用 venv 装 cocotb 遇到同样报错,方向一样:缺的是 libpython 开发库,不是 cocotb 本身。
运行命令(把公开仓库的 experiments/ 挂进容器):
docker run --rm --user $(id -u):$(id -g) -e HOME=/tmp \
-v ~/Project/geek-doc.cn/experiments:/work \
-w /work/eda-lab-cocotb-first-tb geek-eda:0.1.1 make run代码获取:本实验完整代码(
counter.v、test_counter.py)、Makefile 与真实回归输出(out/regression.md、out/seed*.log、out/fail.log)见公开仓库 derekzhuo/geek-doc.cn 的experiments/eda-lab-cocotb-first-tb/。克隆后make run即可复现。
二、实验设计:计数器加了一个溢出标志
DUT 与 iverilog 篇是同一颗 4 位计数器,只多了一个输出 ovf:当 en=1 且 count==15(下一秒必然回绕)时,下一拍 ovf 拉高一个周期。加它是为了让断言演示更有层次——不只比对数据通路(count),还比对标志时序(ovf)。
// counter.v —— 4 位计数器(DUT),同步低有效复位 + 使能 + 溢出脉冲
always @(posedge clk) begin
if (!rst_n) begin
count <= 4'd0;
ovf <= 1'b0;
end else if (en) begin
count <= count + 4'd1;
ovf <= (count == 4'd15);
end else begin
ovf <= 1'b0;
end
endTB 侧的分工与 Verilog 版完全不同,先把整体结构摆出来:
左半边是 Python 世界,右半边是 Verilog 世界,中间 GPI(Generic Procedural Interface,cocotb 对 VPI/VHPI 的抽象层)负责翻译。你写的 dut.count.value 每一次读写,都是穿过这三层进到 vvp 内部的信号堆上操作。理解这条链,后面所有「为什么读到的值不对」的问题都有了排查坐标。
测试文件 test_counter.py 里注册了三个测试:
| 测试 | 类型 | 干什么 |
|---|---|---|
test_reset | 定向 | 复位拉低 3 拍,逐拍断言 count=0、ovf=0 |
test_enable_hold | 定向 | 数 5 拍后 en=0 停 4 拍,断言计数值原地不动 |
test_random_count | 随机回归主测试 | 随机 en 序列跑 300 拍,参考模型逐拍比对 count 与 ovf,共 600 条断言 |
这套「定向测试保底 + 随机测试扫面」的组合是验证方法学的入门标配:定向测试针对你能预想到的场景(复位、保持),写出来快、挂了定位也准;随机测试负责你想不到的角落——en 以 75% 概率随机翻转,300 拍里会出现连击使能、长短不一的暂停、多次回绕,靠人手工枚举这些序列既枯燥又必然遗漏。两者放进同一个 Python 文件、cocotb 按注册顺序串行执行,一次 make 全部跑完。
和 iverilog 篇的 Verilog TB 摆在一起,同一件事两种写法的差别一眼可见:
| 维度 | Verilog TB(iverilog 篇) | Python TB(本篇 cocotb) |
|---|---|---|
| 激励描述 | always #5 clk = ~clk + 大段 initial 时序 | Clock(...).start() 一行 + Python 循环 |
| 随机激励 | $random + 手写种子管理 | random.choice,种子由 RANDOM_SEED 统一播种 |
| 参考模型 | 再写一份 Verilog 逻辑逐拍 $display 比对 | 一个 Python 变量 expected 跟着算 |
| 失败报告 | 自己拼 $display 字符串 | assert 自带 Traceback + 自定义消息 + JUnit XML |
| 结果汇总 | 肉眼看日志找 PASS 字样 | results.xml 标准 JUnit 格式,CI 直接消费 |
| 生态借力 | 几乎没有 | numpy/scapy/pandas 随便调 |
这张表不是踩 Verilog——TB 写在被测语言里有它的场景(比如纯 RTL 团队没有 Python 环境)。但只要项目允许,把验证逻辑放进一门通用语言,几乎是白捡的生产力。
三、Makefile:一行 include 背后的标准写法
cocotb 的 Makefile 长得「头重脚轻」——上半段是你填的变量,下半段就一行:
SIM ?= icarus
TOPLEVEL_LANG ?= verilog
VERILOG_SOURCES = $(PWD)/counter.v
TOPLEVEL = counter
MODULE = test_counter
include $(shell cocotb-config --makefiles)/Makefile.sim五个变量交代清楚全部事实:用什么仿真器(SIM=icarus,换 verilator 就换引擎)、RTL 在哪(VERILOG_SOURCES)、顶层模块名(TOPLEVEL,cocotb 靠它找到 dut 句柄)、Python 测试模块名(MODULE,不需要 .py 后缀)。include 进来的 Makefile.sim 是 cocotb 官方维护的规则库,编译、VPI 库链接、回归执行、JUnit XML 输出全在里面。这就是 cocotb 入门最舒服的一点:构建系统不用学,填五个变量就有工业级回归骨架。
想要自己的逻辑就往后面加普通 make 目标。本篇的 make regress 循环 5 个 seed:
SEEDS ?= 1 2 3 4 5
regress:
@for s in $(SEEDS); do \
rm -rf sim_build; \
RANDOM_SEED=$$s COCOTB_RESULTS_FILE=out/results_seed$$s.xml \
$(MAKE) sim > out/seed$$s.log 2>&1; \
...
doneRANDOM_SEED 是 cocotb 的内建环境变量:cocotb 启动时用它给 Python 的 random 模块播种(日志里能直接看到 Seeding Python random module with 1)。同一份 TB,换 seed 就换一条随机激励轨迹——这就是「约束随机验证」的最小形态。这里有个可复现性纪律要趁早建立:回归里每一次 FAIL 都必须记下 seed,因为「seed=4 挂、seed=5 过」是随机验证的常态,没有 seed 就没有复现入口;反过来,修完 bug 后先用原 seed 验证修复、再放开一批新 seed 扫面,是标准的回归收尾动作。COCOTB_RESULTS_FILE 指定 JUnit XML 落盘路径,每个 seed 一份,CI 系统(Jenkins/GitLab CI)直接吃这个格式。
四、test_counter.py:逐段读懂 Python testbench
先看骨架——时钟、复位、随机激励主循环:
import cocotb
from cocotb.clock import Clock
from cocotb.triggers import FallingEdge, ReadOnly, RisingEdge
@cocotb.test()
async def test_random_count(dut):
cocotb.start_soon(Clock(dut.clk, 10, "ns").start())
await reset_dut(dut)
expected = 0
for cycle in range(300):
await FallingEdge(dut.clk) # 下降沿驱动激励,避开时钟沿竞争
en = random.choice([0, 1, 1, 1]) # 75% 使能,多碰溢出
dut.en.value = en
prev = expected
await RisingEdge(dut.clk)
await ReadOnly() # 等 NBA 落定再采样
if en:
expected = (prev + 1) % 16
assert dut.count.value.to_unsigned() == expected, \
f"cycle {cycle}: count={dut.count.value.to_unsigned()}, expect {expected}"
assert int(dut.ovf.value) == (1 if (en and prev == 15) else 0)四个关键点,每个都是新人必摔跤处:
1. dut 是什么。 cocotb 把 TOPLEVEL 模块包装成 Python 对象注入测试函数,dut.clk、dut.count 就是 RTL 里的信号句柄。写信号用 dut.en.value = en,读信号用 dut.count.value——注意读出来的不是 Python int,是 cocotb 的值对象,转换规则见第六节(这里有 2.x 的真坑)。
2. 协程与触发器。 async def + await RisingEdge(dut.clk) 的意思是「我这个协程睡在这里,等时钟上升沿来了再醒」。多个协程(时钟发生器、复位协程、激励协程)通过 cocotb.start_soon() 并发挂进调度器,谁在等的事件先到来谁先跑。这就是「协程式验证」:没有 Verilog TB 里 fork/join_any 的心智负担,并发就是 Python 的 async。
3. 下降沿驱动、上升沿采样 + ReadOnly。 在上升沿同一时刻又驱动又采样是竞争重灾区。cocotb 社区的稳健写法:激励在 FallingEdge 之后驱动(离下一个采样沿有半周期裕量),采样在 RisingEdge 之后再 await ReadOnly()。为什么需要 ReadOnly?和 iverilog 篇 讲过的 NBA 区域是同一回事:上升沿时刻 RTL 的 count <= count + 1 还没真正写入,此刻读 .value 拿到的是旧值;ReadOnly 把协程挂到当前时间槽的只读阶段,所有非阻塞赋值落定之后才唤醒,读到的一定是新值。不加这一行,你会看到所有断言稳定差一拍——而且不是 bug,是采样窗口错了。
4. 参考模型就活在 Python 里。 expected 变量就是记分板(scoreboard):RTL 该怎么数,Python 跟着怎么数,每拍 assert 一次。300 拍 × 2 条断言(count + ovf)= 600 条检查,失败时断言消息直接给出拍号、实际值、期望值——这比盯波形快一个数量级。
把第 3 点的「下降沿驱动、上升沿后只读采样」画成一拍时序,这是本篇最值得记住的一张图:
顺着时间轴读:上升沿到来的瞬间,RTL 的 count <= count + 1 刚被调度、还没写入,此刻读 .value 拿到的一定是旧值(图中「TB 动作」第一格标注的位置);随后协程睡到下降沿,把下一拍的 en 驱动上去——离下一个上升沿有整整半周期,不存在任何竞争;下一个上升沿之后 await ReadOnly(),等所有非阻塞赋值落定,再读 count 就是加完 1 的新值。把这个节奏养成肌肉记忆,cocotb 里九成的「值不对」疑问都会消失。
五、真实运行:5 个 seed 回归全部 PASS
make run 依次执行 regress(5 个 seed)和 failcase(注错演示)。先看 seed 1 的日志关键段(完整版在实验目录 out/seed1.log):
-.--ns INFO gpi Loaded entry library: '/usr/lib/x86_64-linux-gnu/libpython3.12.so.1.0'
-.--ns INFO pygpi Using Python 3.12.12 interpreter at /opt/venvs/cocotb/bin/python3
0.00ns INFO cocotb.initialize Seeding Python random module with 1
0.00ns INFO cocotb.initialize Initialized cocotb v2.1.0
0.00ns INFO cocotb.initialize Running on Icarus Verilog version 12.0 (stable)
0.00ns INFO cocotb.regression running test_counter.test_reset (1/3)
30.00ns INFO cocotb.counter test_reset PASS: count held 0 during 3-cycle reset
170.00ns INFO cocotb.counter test_enable_hold PASS: count held at 5 for 4 clocks
3210.00ns INFO cocotb.counter test_random_count PASS: 600 assertions, 14 overflow pulses
...
** TESTS=3 PASS=3 FAIL=0 SKIP=0 **日志开头三行正好印证第一节的链条:vvp 先加载 libpython3.12.so.1.0(没有它整个起不来),再启动 venv 里的 Python 解释器,然后 cocotb 播种、接管仿真。末尾的总结表给出每个测试的仿真耗时与速度比——test_random_count 用 0.03 秒真实时间跑完 3040ns 仿真,比率约 118872 ns/s。
再往下看每个测试的耗时列,还能读出一个工程信号:test_random_count 仿真了 3040ns 只占 0.03 秒真实时间,比率约 118872 ns/s——对入门规模的设计,iverilog + cocotb 的组合跑几千拍回归是「秒出结果」的,放心把随机拍数拉大。等设计涨到几十万门、这个比率掉到不能忍的时候,再考虑把 SIM 换成 verilator 或商用仿真器,TB 代码一行不用动。
5 个 seed 的回归汇总(make regress 自动生成,原文见 out/regression.md):
| seed | tests | failures | result |
|---|---|---|---|
| 1 | 3 | 0 | PASS |
| 2 | 3 | 0 | PASS |
| 3 | 3 | 0 | PASS |
| 4 | 3 | 0 | PASS |
| 5 | 3 | 0 | PASS |
每个 seed 的随机轨迹确实不同:seed 1/2/3 各触发 14 次溢出脉冲,seed 4/5 各 13 次(各 seed 日志的 overflow pulses 计数),而 600 条断言逐拍全过——这说明参考模型和 RTL 在 5 条不同的随机轨迹上完全一致。「随机激励 + 参考模型」的威力就在这:你不用手工枚举激励组合,让随机数去踩角落,让断言去报警。
顺带解释一个新手常问的问题:为什么每个 seed 跑之前要 rm -rf sim_build?cocotb 会把编译产物缓存在 sim_build/ 里,源码没变时直接复用——这本来是加速好意,但回归场景下我们要的是每个 seed 一次干净的、可独立复现的运行,缓存残留(比如上一次的 results.xml)会污染统计。清掉它,每个 seed 的日志和 XML 就是自包含的证据链,半年后翻出来也能独立看懂。代价是多花几秒重新编译,对回归场景完全值得。
六、注错演示:一次真实 FAIL 长什么样
PASS 看再多也不如看一次 FAIL。实验里内置了注错开关:INJECT_BUG=1 时,参考模型的复位初值被故意写成 1(off-by-one)——模拟验证工程师最常见的笔误。make failcase 真实输出(out/fail.log 摘录):
Traceback (most recent call last):
File "/work/eda-lab-cocotb-first-tb/test_counter.py", line 96, in test_random_count
assert actual_count == expected, (
AssertionError: cycle 0: count=1, expect 2 (en=1)
assert 1 == 2
...
** test_counter.test_reset FAIL 30.00 ... **
** test_counter.test_enable_hold PASS 140.00 ... **
** test_counter.test_random_count FAIL 50.00 ... **
** TESTS=3 PASS=1 FAIL=2 SKIP=0 **读这份 FAIL 报告的顺序,就是将来你调试真实回归的顺序:先看末尾总结表定位挂掉的测试(test_reset 和 test_random_count 挂、test_enable_hold 过——初值错了 1,但只要 en=0 保持不动就比对不出差异,所以 hold 测试幸存);再往上翻 Traceback,断言消息 cycle 0: count=1, expect 2 (en=1) 直接给出第一案发点:第 0 拍,RTL 数到 1,模型却期望 2——从复位态就偏了 1,off-by-one 的结论十秒钟锁定。整个过程没开波形工具。断言写得越具体(带拍号、带激励值),FAIL 日志就越像一份现成的调试报告。
回归表也会如实记录这次失败:results_fail.xml 里 failures="2",CI 流水线按非零退出码拦截。养成习惯:新 TB 写完,先故意注错一次确认它真的会 FAIL——一个永远不会 FAIL 的 testbench 比没有 testbench 更危险。
七、cocotb 2.x 迁移坑(本篇真实踩到)
本仓库容器里是 cocotb 2.1.0,而网上大量教程还停留在 1.x。本篇实验真实撞上的以及最常被问到的差异,汇总成一张对照表:
| 场景 | 1.x 写法 | 2.1.0 实测行为 | 处置 |
|---|---|---|---|
| 读数值信号 | dut.count.value.integer | .integer 属性已移除 | 用 .to_unsigned()(有符号用 .to_signed()) |
| 读 1-bit 信号 | dut.ovf.value.integer 或 == 1 | .value 返回 Logic 对象,没有 .to_unsigned(),报 AttributeError: 'Logic' object has no attribute 'to_unsigned' | int(dut.ovf.value),或与整数直接 == 比较 |
| 启并发协程 | cocotb.fork(coro()) | fork 已移除 | cocotb.start_soon(coro()) |
| 定时器单位 | Timer(10, units="ns") | units= 关键字已移除 | 位置参数:Timer(10, "ns")(Clock(dut.clk, 10, "ns") 同理) |
第一行就是本篇第一节跑挂的真实原因——初版 TB 对 ovf 也用了 .to_unsigned(),三个测试全灭,日志里 AttributeError 指得清清楚楚。规则好记:多bit 总线是 LogicArray,用 .to_unsigned();单bit 是 Logic,用 int()。从网上抄 1.x 代码跑不动时,先查这张表再怀疑人生。
再补两个本节实验顺带确认的工程坑:
| 真实报错/现象 | 原因 | 处置 |
|---|---|---|
find_libpython was not able to find a libpython(make 阶段即死) | Python 环境缺 libpython3.xx.so 共享库(精简镜像/某些 venv 高发) | 装 libpython 开发包(Debian/Ubuntu:apt-get install libpython3.12),或设 LIBPYTHON_LOC 指向 .so 绝对路径 |
| 断言稳定差一拍:期望值总是比读到的大 1 | RisingEdge 后立刻读 .value,采样到 NBA 落定前的旧值 | 采样前 await ReadOnly();激励改到 FallingEdge 后驱动 |
八、动手建议:三个台阶
- 换仿真器:
make regress SIM=verilator(容器里 Verilator 5.020 可用)。同一份 Python TB 一行不改换引擎,体会「cocotb 不绑定仿真器」这句话的分量——verilator coverage 篇 用的就是这颗引擎的另一面。 - 加失败注入维度:把 RTL 里
ovf <= (count == 4'd15)改成4'd14,跑make regress,观察 5 个 seed 的 ovf 断言在哪一拍首次报警、各 seed 挂的位置是否相同。 - 写第 4 个测试:复位释放途中(
rst_n拉低期间)强行打en=1,断言 count 仍然保持 0——验证「复位优先级高于使能」这条 RTL 语义,并用dut._log.info打一条你自己的 PASS 消息。这个练习的价值在于完整走一遍「加@cocotb.test()→ 重跑回归 → 看总结表多一行」的闭环,以后往 TB 里加场景就是肌肉动作。
这一篇在知识体系里的位置
本篇补上了仿真线的验证方法学一角:前面 iverilog 仿真入门 是同一颗计数器的 Verilog TB 版对照(两篇对着读,最能体会 Python TB 的表达力差);想看波形侧的产物怎么落,去 iverilog VCD 波形篇;想给这颗计数器量「测试覆盖了多少代码」,接 verilator coverage 篇——覆盖率正是「我的随机回归够不够狠」的量化答案。仿真器底层概念(事件调度、NBA 区域)可回看 concepts 专区 相关文章。
总结
cocotb 入门就一句话:Verilog 只管 DUT,testbench 用 Python 写——Clock 给时钟、FallingEdge 后驱动激励、RisingEdge + ReadOnly 后采样断言、参考模型用 Python 变量逐拍比对、RANDOM_SEED 循环出多 seed 回归,再用一次故意注错确认你的 TB 真的会 FAIL,这套骨架能原样搬到任何规模的验证项目里。