Metadata-Version: 2.4
Name: cocotb_kernel
Version: 1.0.5
Summary: Jupyter kernel for cocotb
Author-email: Matthew Michilot <matthew.michilot@gmail.com>
Requires-Python: >=3.11,<4
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Framework :: cocotb
Classifier: Framework :: Jupyter
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
License-File: LICENSE
Requires-Dist: cocotb>=1.8.1,<2
Requires-Dist: ruff ~= 0.5.0 ; extra == "lint"
Requires-Dist: mypy ~= 1.10.0 ; extra == "lint"
Project-URL: Source, https://github.com/mmichilot/cocotb_kernel
Provides-Extra: lint

# cocotb Jupyter Kernel
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/mmichilot/cocotb_kernel/HEAD?labpath=example%2FQuickstart+Guide.ipynb)

This kernel adds support for using [cocotb](https://docs.cocotb.org/en/stable/) 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](https://docs.cocotb.org/en/stable/library_reference.html#cocotb.runner.Simulator), then
having a cocotb test module launch ipykernel, which will connect to the notebook and execute code cells.

## Installation
Prerequisites:
- Python 3.11+
- 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.
```bash
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](https://docs.cocotb.org/en/stable/library_reference.html#cocotb.runner.Simulator) 
`build()` and `test()` arguments, with a few exceptions, as shown:

```toml
# 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]
verilog_sources = ["hdl/foo.sv", "../hdl/foo.sv"] # specify sources relative to cocotb.toml
vhdl_sources = ["hdl/*.vhdl", "**/*.vhdl"]        # wildcards are also supported

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

# 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.

## Planned Features
- Move wavedrom support into kernel (cocotb v2.0 removes the wavedrom module)

