Cocotb学习之路（1）— Cocotb 的安装与仿真

一、前言

Cocotb 作为基于 Python 的 Verilog/VHDL 仿真库，能让我们用 Python 灵活编写测试用例，搭配 Verilator 仿真引擎和 GTKWave 波形查看工具，构成一套轻量高效的仿真环境。

我们要使用的工具如下：

• Python：Cocotb 的运行基础，推荐 3.10 及以上版本
• Cocotb：核心仿真库，用于连接 Python测试代码与硬件描述语言
• Verilator：开源 Verilog 仿真引擎，负责解析 Verilog 代码并执行仿真
• GTKWave：波形查看工具，用于可视化仿真结果，调试硬件逻辑

参考文章：基于 Python 的 Cocotb 仿真环境配置

二、工具安装

1、Python 环境配置

首先确保系统安装了 Python 及相关工具，推荐 Python 3.10+

sudo apt update
sudo apt install python3 python3-pip python3-venv -y

2. 安装 Cocotb 及依赖库

升级 pip 和 wheel（确保安装兼容性）

pip3 install --upgrade pip wheel

安装 Cocotb 及相关依赖

pip3 install cocotb cocotb-bus pytest

3. Verilator 安装

Verilator 提供两种安装方式，按需选择即可：

方式 1：apt 快速安装（推荐新手）

适合不需要最新版本的场景，安装简单无需编译：

sudo apt install verilator -y
# 验证安装成功
verilator --version

方式 2：源码安装（需要最新版本时）

如果 apt 安装的版本过低（如需要 5.0 以上版本），可通过源码编译：

# 1. 安装编译依赖
sudo apt install git perl python3 make autoconf g++ flex bison libfl2 libfl-dev zlibc zlib1g zlib1g-dev -y

# 2. 克隆源码并切换版本（以 v5.036 为例，可替换为最新版本）
git clone https://github.com/verilator/verilator.git
cd verilator
git checkout v5.036

# 3. 编译安装
autoconf
./configure
make -j$(nproc)  # 多线程编译，加快速度
sudo make install

# 4. 处理版本冲突（若系统已有旧版本）
# 编辑 ~/.bashrc，将 /usr/local/bin 加入 PATH 前端
echo 'export PATH=/usr/local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

4. GTKWave 安装（波形查看工具）

GTKWave 是开源免费的波形查看工具，支持 .vcd 和 .fst 格式文件：

sudo apt install gtkwave -y

# 常用启动命令（后续仿真后使用）
gtkwave logs/dump.vcd &

三、创建工程

新建设计文件 dff.sv 如下所示：

`timescale 1us/1ns

module dff (
    input logic         clk,
    input logic  [3:0]  din,
    output logic [3:0]  qout
);

    always @(posedge clk) begin
        qout <= din;
    end

endmodule

编写测试文件如下所示：

import random
import cocotb
from cocotb.clock import Clock
from cocotb.triggers import FallingEdge
import logging

@cocotb.test()
async def test_dff_simple(dut):
    """ The test input din can be correctly passed to the output qout """
     # Create a logger for this testbench
    logger = logging.getLogger("my_testbench")
    logger.setLevel(logging.DEBUG)
    logger.debug("This is a debug message")
    logger.info("This is an info message")
    clock = Clock(dut.clk, 10, units="us")
    cocotb.start_soon(clock.start())

    for i in range(10):
        val = random.randint(0, 7)
        dut.din.value = val
        await FallingEdge(dut.clk)
        logger.info(f"Cycle {i}: din = {dut.din.value}, qout = {dut.qout.value}")
        assert dut.q.value == val, f"In {i} cycle，output(qout) is {dut.q.value}，expect is {val}"

编写运行makefile文件如下所示：

export PYTHONPATH := $(PWD)/testbench:$(PYTHONPATH)

export LANG := en_US.UTF-8
export LC_ALL := en_US.UTF-8
export PYTHONIOENCODING := utf-8

TOPLEVEL_LANG = verilog

VERILOG_SOURCES = $(PWD)/dff.sv
TOPLEVEL = dff

MODULE = test

SIM ?= verilator

LOG_DIR ?= logs

SIM_LABEL := $(if $(strip $(SIM)),$(strip $(SIM)),default_sim)

export VERILATOR_TRACE=1

run: $(LOG_DIR)
	$(MAKE) --no-print-directory sim

clean::
	@echo "[cocotb] The simulation generated files are being cleaned up"
	@rm -rf $(LOG_DIR) sim_build results.xml
	@rm -f *.log transcript modelsim.ini dump.vcd
	@rm -rf __pycache__

include $(shell cocotb-config --makefiles)/Makefile.sim

.PHONY: run clean

$(LOG_DIR):
	@mkdir -p $@

四、仿真运行

使用make命令运行如下所示：

五、查看波形

执行如下命令打开波形

gtkwave dump.vcd

打开波形后如下所示