cocotb by cocotb

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

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

Cocotb requires:

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

pip install cocotb

!!! Windows Users !!! See here for installation instructions.

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

For detail on how to install the development version of cocotb, see the lastest documentation.

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.fork(clock.start())  # Start the clock

    for i in range(10):
        val = random.randint(0, 1)
        dut.d <= val  # Assign the random value val to the input port d
        await FallingEdge(dut.clk)
        assert dut.q == 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 the wiki.

Tutorials, examples and related projects

For more related resources please check the wiki and the list of projects depending on cocotb.

Cocotb is licensed under the Revised BSD License.  Full license text below.

###############################################################################
# Copyright (c) 2013 Potential Ventures Ltd
# Copyright (c) 2013 SolarFlare Communications Inc
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#     * Redistributions of source code must retain the above copyright
#       notice, this list of conditions and the following disclaimer.
#     * Redistributions in binary form must reproduce the above copyright
#       notice, this list of conditions and the following disclaimer in the
#       documentation and/or other materials provided with the distribution.
#     * Neither the name of Potential Ventures Ltd,
#       SolarFlare Communications Inc nor the
#       names of its contributors may be used to endorse or promote products
#       derived from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# DISCLAIMED. IN NO EVENT SHALL POTENTIAL VENTURES LTD BE LIABLE FOR ANY
# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
###############################################################################

Project Meta

  • Registered on LibreCores 3 months ago
  • Project started 7 years ago
  • Last commit 18 days ago

Commits

{"labels":[2013,2014,2015,2016,2017,2018,2019,2020],"series":[[501,311,499,269,130,187,399,636]]}

Commits per year

Contributors

{"labels":[2013,2014,2015,2016,2017,2018,2019,2020],"series":[[10,12,21,20,17,31,49,40]]}

Unique contributors per year

Releases

v1.3.2 is is the latest of 17 releases.

  • v1.3.2
    Jul 8, 2020 25b242e
  • v1.3.2rc1
    Jul 8, 2020 a6f6914
  • v1.4.0
    Jul 8, 2020 0b2dc3e
  • v1.4.0rc2
    Jul 7, 2020 e0f4234
  • v1.4.0rc1
    Jun 23, 2020 620749c
  • v1.3.1
    Mar 15, 2020 ec54de5
  • v1.3.1rc1
    Mar 15, 2020 6e8e222
  • v1.3.0
    Jan 8, 2020 c8916ab
  • v1.3.0rc2
    Jan 4, 2020 927f10a
  • v1.3.0rc1
    Jan 3, 2020 dafe53f
  • v1.2.0
    Jul 24, 2019 b172f00
  • v1.2.0rc1
    Jul 20, 2019 73b6742
  • v1.1
    Jan 23, 2019 12e40c4
  • v1.0
    Feb 15, 2015 c1e259c
  • v0.4
    Feb 25, 2014 b99219e
  • v0.3
    Sep 26, 2013 707680a
  • v0.2
    Jul 19, 2013 bc4ac59

Languages

{"labels":["Others","Python","reStructuredText","make","VHDL","Verilog-SystemVerilog","C\/C++ Header","C++","Markdown","YAML"],"series":[983,100,27,59,39,29,17,14,6,6]}

Share of languages used

Data Sheet
Project Web Site
https://github.com/cocotb/cocotb.git
Issue Tracker
Last activity 1 day ago
v1.3.2 released 1 month ago
Primary language: Python
295 open issues
57 open pull requests
233 forks
100 watchers
577 stars
2932 commits by 133 contributors
Stuart Hodgson Chris Higgs chiggs Eric Wieser Kaleb Barrett
0,1,14,15,15,5,8,4,7,5,17,8,3,3,4,17,6,5,5,17,3,16,11,12,16,22,11,15,58,15,4,8,17,9,20,59,41,23,59,32,58,25,17,16,21,6,9,0,15,17,4,0,0,0,0

activity over the last year

LibreCores data updated 1 day ago