极客工场

Appearance

共 3,273 字预计阅读约 11 分钟

异步 FIFO 的 cocotb 验证实测：格雷码指针空满边界与随机读写回归 ​

更新时间：2026-10-25。本文是「集成电路大类 · 芯片设计」中间层（intermediate）的一篇实验文。理论篇 多 bit CDC：异步 FIFO 与 Gray 码指针设计 已经把异步 FIFO 的结构讲透了：双口 RAM 两端各跑各的时钟，过域的只有格雷码形式的读写指针，空满判断靠保守比较。格雷码指针 一篇则回答了「为什么指针跨域必须用格雷码」。理论讲完了，问题还剩一半：怎么证明这块 FIFO 真的对？空信号撤得及不及时、满信号会不会误杀、异步时钟下数据会不会乱序——这些靠读 RTL 是读不出信心的。本篇用 cocotb（一个用 Python 协程写 testbench 的验证框架）把这台 8 位宽、16 深度的异步 FIFO 放到 Icarus Verilog 仿真器里真跑，两条测试全绿。

本文要回答的问题 ​

  • cocotb 相比纯 Verilog testbench，验证异步 FIFO 时省了什么、多了什么？
  • 「单写读」这条最短的测试为什么必须有？它兜住的是哪类 bug？
  • 随机背靠背回归怎么构造，才能同时压到空、满两个边界？
  • 双时钟异步驱动下，「数据完整性」的可机检判据长什么样？

先把回归结果摆上来，四个数字全部出自后文日志：

异步 FIFO cocotb 回归：2 条测试全 PASS，200 笔数据零乱序

这张图的关键在分母与结构：绿色 2/2 是两条用例全过；蓝色 200 是随机用例里跨域搬运的 token 数——不是「跑了 200 拍」这种含糊说法，而是 200 个值写入再读出、Python 侧逐笔比对顺序与内容全等。红色 7/11 ns 是刻意挑的两个互质附近的周期，让写读时钟相位关系随时间扫过各种组合，空满边界的运气成分被系统性地榨出来。

一、验证环境长什么样：RTL 之外全是 Python ​

整个验证环境的角色划分，一张图看清：

chip-design/intermediate/exp-async-fifo-cocotb-verify.md D2 示意图

读这张图抓住左右分界：左边蓝色是 Python 世界——时钟、激励、断言全部写成协程，cocotb.start_soon 一拉起就是并发进程，不需要 Verilog 里 fork/join 那套写法；中间灰色 VPI 桥是 cocotb 与仿真器的接口层，Python 给 dut.wr_en.value 赋值、读 dut.empty.value，背后都是对 Icarus 信号句柄的调用；右边橙色才是真正被测的 RTL。两个紫色时钟协程各跑各的周期，这就是「异步」的来源——异步时钟不是 RTL 里写的，是测试环境给的两个独立节奏。

这套结构对验证工程师最大的红利是「记分板免费」：Python 侧维护两个 list，writer 协程每推一笔就 append 到 written，reader 协程每收一笔就 append 到 received，回归结束一句 assert written == received 就是完整的数据完整性判据。纯 Verilog testbench 里要做同样的事，得自己维护队列或写文件比对，代码量翻几倍还容易出错。

二、两条测试各兜什么边界 ​

冒烟用例：单写读，专抓「指针根本没通」 ​

第一条用例只做一件事：写一笔 0xA5，等 empty 撤掉，读出来比对。它存在的意义是把最粗的接线错误与最隐蔽的边界错误分开。如果格雷码转换写反了、两级同步少打了一拍、空满条件用错了指针位，FIFO 的表现往往是「写了永远读不到」——empty 永不撤销。这类 bug 在复杂随机测试里会被淹没成超时，而在单写读用例里 99 ns 仿真时间内直接现形。

用例里有一个细节值得抄走：wait_not_empty 轮询 empty 标志最多 40 拍，而不是「写完后数固定几拍」。原因是 empty 的撤销有打拍同步加寄存输出的数拍延迟——写指针先变、格雷码过两级同步器到读域、再参与空判断，这个延迟与两时钟相位有关，写死拍数的 testbench 换一个时钟配比就假失败。轮询标志是异步设计验证的通用正确姿势。

随机回归：200 笔背靠背，压满也压空 ​

第二条用例是主菜。写侧每拍以 0.8 概率发起写、读侧每拍以 0.7 概率发起读，各带独立随机源，200 笔 token 背靠背穿过 FIFO。写比读快一点点（0.8 对 0.7），FIFO 会被逐渐填满直到 full 反压生效；而读侧随机停顿又会让 FIFO 反复回到接近空的状态——空、满两个边界在一次回归里被反复穿越，这正是格雷码指针最容易出错的工况（空满判断恰好是指针相等加最高位翻转的精细比较）。

写侧协程里埋着一个真金白银的教训，注释里写得很直白：

python
async def writer():
    # 负沿采样/驱动：正沿后立即读 full 会撞上寄存器 NBA 更新（读到旧值），
    # 旧 full=0 时写入已满 FIFO 会覆盖丢数据，读者永远等不齐
    sent = 0
    while sent < n_tx:
        await FallingEdge(dut.wclk)
        if int(dut.full.value) == 0 and rng.random() < 0.8:
            v = rng.randrange(256)
            dut.wdata.value = v
            dut.wr_en.value = 1
            written.append(v)
            sent += 1
        else:
            dut.wr_en.value = 0

所有采样与驱动都放在时钟负沿。如果正沿后立即读 full，撞上的是寄存器非阻塞赋值（NBA）更新前的旧值——full 其实还是 0，于是往一个已满的 FIFO 里再写一笔，直接把未读数据覆盖掉。这种 bug 的表象是「读者永远等不齐 200 笔」，排查时极易冤枉 RTL，实际是 testbench 自己的竞争。这是 cocotb 新手必踩的坑，本篇原样保留以示警戒。

还有一个设计决定值得说透：为什么是「随机概率 0.8/0.7」而不是定向写满再读空。定向序列（写 16 笔填满、再读 16 笔排空）能精确命中空满各一次，但它测的是「设计者的想象」——只覆盖你提前想到的时序。随机停顿的价值在于它会产生设计者没想到的相位组合：写侧连续三拍突发撞上读侧连续两拍停顿，FIFO 在 6 ns 与 9 ns 的相位漂移下从「接近满」滑到「真满」的那几拍，full 信号的拉起、写使能的反压、写指针的停走，每一拍都是格雷码比较器的一次真实考核。200 笔跑下来，full 与 empty 各被穿越的次数远超定向序列能给的覆盖。这也是为什么回归命令里带 WAVES=1：仿真落出 FST 波形，万一哪天真翻红了，可以拉回波形逐拍定位，而不是对着一行 FAIL 干瞪眼——可复现性（固定种子）与可观测性（波形落盘）是回归的两个保命绳。

三、实测实录：两条用例全绿 ​

cocotb 回归实录：2 用例全 PASS

这份实录读法分三层：最上面两行 running single_write_read / passed 说明冒烟用例 99 ns 内通过；中间 200 tokens delivered in order across async clocks OK 是随机用例里 Python 断言通过后主动打的一句话——「in order across async clocks」三个词就是全文的核心主张，数据在 6 ns 与 9 ns 两个异步时钟域之间搬运 200 笔，顺序与内容分毫不差；最下面的回归汇总表给出 TESTS=2 PASS=2 FAIL=0 SKIP=0，合计仿真 2722.50 ns、真实耗时 0.15 秒，仿真比约 18000 ns/s。

把冒烟与随机两条用例的关键行原样摘录一段，便于逐条核对：

exp-log
0.00ns INFO     cocotb.regression                  Found test test_async_fifo.single_write_read
0.00ns INFO     cocotb.regression                  Found test test_async_fifo.random_back_to_back
0.00ns INFO     cocotb.regression                  running single_write_read (1/2)
99.00ns INFO     cocotb.regression                  single_write_read passed
99.00ns INFO     cocotb.regression                  running random_back_to_back (2/2)
2722.50ns INFO     cocotb.async_fifo                  200 tokens delivered in order across async clocks OK
2722.50ns INFO     cocotb.regression                  random_back_to_back passed
** TESTS=2 PASS=2 FAIL=0 SKIP=0                      2722.50           0.15      18056.70  **

这段摘录覆盖了从用例发现、逐条执行到最终汇总的完整证据链。注意 Seeding Python random module with 1792863731 这一行（在日志前部）：cocotb 每次跑都会给随机种子，本回归的 writer/reader 激励由 random.Random(20261020) 这个固定种子源驱动，也就是说这次 PASS 是可复现的确定性回归，不是撞大运。重跑同一仓库同一命令，激励序列逐拍一致。

维度纯 Verilog testbench本实验的 cocotb 方案
时钟生成每个时钟一个 initial 块一行 Clock(dut.wclk, 7, units="ns")
随机激励$random + 手写约束Python random，任意分布
数据记分板队列/文件比对，数十行两个 list + 一句 assert
边界判定手写状态机轮询标志协程里 for 循环轮询，超时即 raise
仿真器需支持 SV 的商业工具更顺手Icarus Verilog 开源即可跑

四、这次回归证明了什么、没证明什么 ​

先说证明了的：在 6/9 ns 与 7/11 ns 两种异步时钟配比下，这台 FIFO 的数据通道、空标志撤销、满标志反压在 200 笔随机压力下功能正确。尤其「空满反复穿越」这个工况被随机停顿自然覆盖到了，这比定向写满再定向读空的老式 testbench 更接近真实流量。值得强调的是空满判断的保守性：因为对方域的指针要打两拍才到，本域看到的永远是「稍旧」的对方指针——写侧以为还没空那么多、读侧以为还没满那么多，两边都宁可少装一点也绝不多装。这次回归里 200 笔零丢失零乱序，间接验证了这份保守没有退化成死锁或假满：FIFO 既没有把未写完的数据放给读侧，也没有在明明有空间时永久反压写侧。

再说没证明的，划清边界很重要。第一，仿真里两级同步器功能永远正确，亚稳态在理想数字仿真中不可见——格雷码指针真正要兜的位间偏移与亚稳态风险，需要 多比特跨时钟域翻车实证 那样显式注入偏移模型的对照实验去暴露，本篇与它恰好互补：那篇证明「为什么必须格雷码」，本篇证明「格雷码 FIFO 在协议层面行为正确」。第二，cocotb 的断言是「最终一致性」——数据对不对；至于「满信号拉起后还能否安全再写一拍」这类拍级时序契约，需要断言更细的形式化属性或 SVA 才能覆盖，这是后续可以增强的方向。

给读者的延伸练习：把随机用例的写概率从 0.8 调到 0.3（读快于写），FIFO 会长期贴着空运行，empty 边界被更密集地敲打；再把 n_tx 提到 2000，回归时间仍在秒级——cocotb + Icarus 的组合在这个规模上几乎没有成本压力，可以放心把压力加满。

这一篇在知识体系里的位置 ​

一句话总结 ​

异步 FIFO 的验证核心不是「跑很多笔」，而是让空满边界在异步时钟下被随机流量反复穿越，并用 Python 记分板做逐笔数据比对。本篇用 cocotb 两条用例实测：单写读冒烟 99 ns 通过、200 笔随机背靠背跨 6/9 ns 双时钟零乱序，TESTS=2 PASS=2；同时实录了「正沿采样 full 撞 NBA 旧值」这个 testbench 侧的经典坑——采样驱动一律放负沿。

实验环境 ​

  • 机器/系统：云主机 S6.4XLARGE32 16C32G / Ubuntu 22.04（eda-golden-v1 镜像）
  • 工具版本：cocotb 1.8.1 + Icarus Verilog version 11.0 (stable)（版本行照抄日志：Running on Icarus Verilog version 11.0、Running tests with cocotb v1.8.1）
  • 日期：2026-10-25
  • 完整命令：bash run_all.sh async-fifo（内部执行 make -f /opt/eda-venv/lib/python3.10/site-packages/cocotb/share/makefiles/Makefile.sim SIM=icarus WAVES=1 TOPLEVEL_LANG=verilog VERILOG_SOURCES="rtl/async_fifo.v" TOPLEVEL=async_fifo MODULE=test_async_fifo COMPILE_ARGS="-g2012"，即 iverilog 编译后由 vvp 加载 libcocotbvpi_icarus 运行回归）

代码获取 ​

完整 RTL、cocotb 测试与 Makefile 已同步到公开仓库：geek-doc.cn/experiments/exp-async-fifo-cocotb-verify，克隆后进入该目录执行 make run（需 Python 环境装 cocotb 与 iverilog）即可复现本文全部结果。