Cocotb

info

The source code for this example can be found in examples/simple_cocotb

warning

Verilator is the less supported tool by cocotb, we recommand using Icarus Verilog.

Description

This example shows how to do simulation using DPI with SoCMake.

In this case, we will have an IP library called adder, that is just a simple combinatorial adder with only 1 file, adder.v. We will also have a python cocotb testbench simple_cocotb_example.py

Example

Directory structure

Lets take a look at the directory structure of the example first.

.
├── adder
│   ├── adder.v
│   └── CMakeLists.txt
├── CMakeLists.txt
├── python_requirement.txt
└── simple_cocotb_example.py

We have a directory adder/ that contains the adder IP block, it as its own CMakeLists.txt to make it easier to reuse in a larger project.

tip

For a design this simple it is not really necessary to have a separate CMakeLists.txt, but it is a good practice anyways.

adder/adder.v

Adder verilog file is just a simple two 5bit inputs, and a 5bit output module.

adder/adder.v

module adder(
    input [4:0] NUM1,
    input [4:0] NUM2,
    output [4:0] SUM
    );

    assign SUM = NUM1 + NUM2;
endmodule

adder/CMakeLists.txt

There is nothing new in this file from previous examples.

hello/CMakeLists.txt

add_ip(adder
    DESCRIPTION "Just a simple adder")

ip_sources(${IP} VERILOG
    adder.v
    )

python_requirements.txt

Python requirement file, used to install the recommanded cocotb version in a virtual environment

python_requirements.txt

cocotb==1.8.1

simple_cocotb_example.py

This is a simple python file using cocotb to create a testbench.

simple_cocotb_example.py

import cocotb
from cocotb.triggers import Timer

class Colors:
    """ANSI escape codes for terminal color output."""

    RESET = "\033[0m"
    RED = "\033[31m"
    GREEN = "\033[32m"
    YELLOW = "\033[33m"
    BLUE = "\033[34m"
    MAGENTA = "\033[35m"
    CYAN = "\033[36m"
    WHITE = "\033[37m"
    BOLD = "\033[1m"

@cocotb.test()
async def simple_cocotb_example(dut):
  """Test a simple adder: drives NUM1 and NUM2 with equal values and checks SUM."""
  dut._log.info("Running simple cocotb example test...")

  for i in range(10):
    dut._log.info(f"{Colors.YELLOW}{Colors.BOLD}Test iteration {i+1}.{Colors.RESET}")
    # Set adder inputs
    dut.NUM1.value = i
    dut.NUM2.value = i
    expected_result = i + i
    await Timer(5, units="ns")
    result = dut.SUM.value
    if(expected_result == result):
      dut._log.info(f"{Colors.GREEN}{Colors.BOLD}Test passed.{Colors.RESET}")
    else:
      dut._log.info(f"{Colors.RED}{Colors.BOLD}Test failed.{Colors.RESET}")
      raise ValueError(f"{Colors.RED}{Colors.BOLD}Expected: {expected_result} - Obtained: {result}{Colors.RESET}")

CMakeLists.txt

And finally we need a top CMakeLists.txt that will assemble the full project and create simulation targets.

CMakeLists.txt

cmake_minimum_required(VERSION 3.27)
project(simple_cocotb_example CXX)

include("../../SoCMakeConfig.cmake")

option_enum(SIMULATOR "Which simulator to use" "iverilog;xcelium;verilator;vcs" "iverilog")

# Support of Verilator is limited with cocotb 
# Cocotb 1.8.1 and verilator 5.012 works together, that's why we build this exact version
# If verilator does not work with cocotb on your machine, it's recommended to use an other tool
if(${SIMULATOR} STREQUAL "verilator")
    verilator_build(VERSION 5.012 EXACT_VERSION)
endif()

add_subdirectory(adder)

cocotb(adder
    TOP_MODULE adder
    COCOTB_MODULE ${PROJECT_NAME}
    SIM ${SIMULATOR}
    OUTDIR ${PROJECT_BINARY_DIR}
    PYTHONPATH ${CMAKE_CURRENT_LIST_DIR}
)

help()

info

If you want to use verilator, it will be built using verilator_build function in the version 5.012, it takes around 5min to build. Doing so, we can be sure that it will be working as this environment, composed of verilator 5.012 and cocotb 1.8.1 is working well with SoCMake.

We can add the adder IP as a subdirectory with add_subdirectory() CMake function.

The SoCMake cocotb() function is used with the argument TOP_MODULE to give the RTL top level to simulate, COCOTB_MODULE to give the python file to be used as the testbench. More information about it can be found in the API documentation.

Running the simulation

To run the simulation, we first need to create a python environment, then activate it to install the recommanded cocotb version:

python3 -m venv .venv                  # Create python virtual environment
source .venv/bin/activate              # Activate python virtual environment
pip install -r python_requirements.txt # Install recommanded cocotb version

Now, we can run the simulation the same way as usual:

mkdir build && cd build
cmake ../ -DSIMULATOR=iverilog              # Configure project
make run_adder_cocotb_simple_cocotb_example # Build and run testbench