cocotb Jupyter Kernel

This kernel adds support for using cocotb within Jupyter notebooks.

Why is a dedicated kernel needed?

cocotb works in conjunction with an HDL simulator. As such, attempting to import cocotb within a notebook will not work because no simulator is attached. This kernel works by first building the HDL design and launching the simulator using cocotb's runners, then having a cocotb test module launch ipykernel, which will connect to the notebook and execute code cells.

Installation

Prerequisites:

• Python >=3.11,<3.14 (cocotb 2.0.1 supports up to 3.13)
• JupyterLab 4+ or Jupyter Notebook 6+
• An HDL simulator (such as Icarus Verilog, Verilator, or GHDL)

After installing the prerequisites, the kernel can be installed via pip.

pip install cocotb_kernel

To complete the installation of kernel, execute one of the following commands:

# Install to Jupyter's user directory, ~/.local/share/jupyter/kernel
python -m cocotb_kernel.install --user

# or, if using conda / venv
python -m cocotb_kernel.install --sys-prefix

# or, a custom prefix (Warning: kernel might not be detected by Jupyter)
python -m cocotb_kernel.install --prefix PREFIX

# or, install to Jupyter's base directory, /usr/local/share/jupyter (requires root)
sudo python -m cocotb_kernel.install

Usage

Before launching the kernel, create a TOML file named cocotb.toml within the project's root directory (similar to cocotb's Makefile).

The TOML file follows the cocotb runner build() and test() arguments, with a few exceptions, as shown:

# The simulator to build and simulate the HDL design
# https://docs.cocotb.org/en/stable/simulator_support.html
simulator = "icarus"

# The top level HDL module
hdl_toplevel = "foo"

# The language of the top level HDL module
hdl_toplevel_lang = "verilog"

# Optional: Verilog parameters or VHDL generics
[parameters]

# Build options
# https://docs.cocotb.org/en/stable/library_reference.html#cocotb.runner.Simulator.build
[build]
sources = ["hdl/foo.sv", "../hdl/foo.sv", "hdl/*.vhdl", "**/*.vhdl"] # specify sources relative to cocotb.toml

# Optional: Defines to set for building
[build.defines]

# Optional: Test options
# https://docs.cocotb.org/en/stable/library_reference.html#cocotb.runner.Simulator.test
[test]

# Optional: Extra environment variables to set for testing
[test.extra_env]

Once the TOML file is created, navigate to or launch JupyterLab within the project's root directory and create or open a notebook with the cocotb kernel.