Skip to main content

cocotb is a coroutine based cosimulation library for writing VHDL and Verilog testbenches in Python.

Project description

cocotb is a coroutine based cosimulation library for writing VHDL and Verilog testbenches in Python.

Documentation Status Build Status PyPI Gitpod Ready-to-Code codecov

Installation

The current stable version of cocotb requires:

  • Python 3.6+
  • Python development packages (Python/C API headers and embedding library)
  • GCC 4.8.1+, Clang 3.3+ or Microsoft Visual C++ 14.21+ and associated development packages
  • GNU Make 3+
  • An HDL simulator (such as Icarus Verilog, Verilator, GHDL or other simulator)

After installing these dependencies, the latest stable version of cocotb can be installed with pip.

pip install cocotb

For more details on installation, including prerequisites, see the documentation.

For details on how to install the development version of cocotb, see the preliminary documentation of the future release.

!!! Bus and Testbenching Components !!! The reusable bus interfaces and testbenching components have recently been moved to the cocotb-bus package. You can easily install these at the same time as cocotb by adding the bus extra install: pip install cocotb[bus].

Usage

As a first trivial introduction to cocotb, the following example "tests" a flip-flop.

First, we need a hardware design which we can test. For this example, create a file dff.sv with SystemVerilog code for a simple D flip-flop. You could also use any other language a cocotb-supported simulator understands, e.g. VHDL.

// dff.sv

`timescale 1us/1ns

module dff (
    output logic q,
    input logic clk, d
);

always @(posedge clk) begin
    q <= d;
end

endmodule

An example of a simple randomized cocotb testbench:

# test_dff.py

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

@cocotb.test()
async def test_dff_simple(dut):
    """ Test that d propagates to q """

    clock = Clock(dut.clk, 10, units="us")  # Create a 10us period clock on port clk
    cocotb.start_soon(clock.start())  # Start the clock

    for i in range(10):
        val = random.randint(0, 1)
        dut.d.value = val  # Assign the random value val to the input port d
        await FallingEdge(dut.clk)
        assert dut.q.value == val, "output q was incorrect on the {}th cycle".format(i)

A simple Makefile:

# Makefile

TOPLEVEL_LANG = verilog
VERILOG_SOURCES = $(shell pwd)/dff.sv
TOPLEVEL = dff
MODULE = test_dff

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

In order to run the test with Icarus Verilog, execute:

make SIM=icarus

asciicast

For more information please see the cocotb documentation and our wiki.

Tutorials, examples and related projects

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cocotb-1.6.2.tar.gz (209.9 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page