CocoTB Simulation Directory

This directory contains simulation files for running Cocotb tests with GHDL, NVC, or Verilator backends.

Running Tests

Basic Usage


# Run a specific VHDL test with GHDL (Default)
export SIM=ghdl
python3 tests/units/test_edge_detector.py

# Switch to NVC (VHDL)
export SIM=nvc
python3 tests/units/test_edge_detector.py

# Switch to Verilator (Verilog/SystemVerilog)
export SIM=verilator
python3 tests/units/test_verilog_counter.py

Using the Simulation Engine

The recommended way to run simulations is through the unified run_simulation() API:


from engine.simulation import run_simulation

run_simulation(
    top_level="wrapper_smi_sync",
    module="test_smi_sync",
    generics={"DATA_WIDTH": 32},
    simulator="ghdl",  # ghdl, nvc, or verilator
    waves=True,
)

Unit Tests (Generated)

Templates for all VHDL units in src/units/ are available in sim/cocotb/tests/units/. These were generated using cocotb-testgen.

Test File	Status (NVC)
`tests/units/test_edge_detector.py`	✅ Verified Logic (GHDL/NVC)
`tests/units/test_verilog_counter.py`	✅ Verilator Verification
`tests/units/*.py`	✅ Smoke Tests

Available Test Scripts (Manual)

Test File	Description
`tests/test_uart_new.py`	UART sniffer testbench
`tests/test_system_top.py`	Full system top-level tests
`tests/test_verilog_counter.py`	Verilator smoke test
`tests/test_system_top_snd.py`	System top send path tests
`tests/test_spi_rcv.py`	SPI receiver tests
`tests/test_spi_injector.py`	SPI injector tests
`tests/test_dds.py`	DDS/phase accumulator tests
`tests/test_engine_demo.py`	Simulation engine demo
`tests/run_test_system_top.py`	Pytest runner for system top

Note: NVC is the recommended simulator for full behavioral testing due to GHDL VPI limitations with scalar ports.

Directory Structure


cocotb/
├── engine/          # Simulation orchestrator
│   ├── backends/    # GHDL, NVC, and Verilator backends
│   ├── simulation.py    # Main run_simulation() entry point
│   └── ...
├── tests/           # Test files
├── tb/              # Testbench infrastructure (drivers, monitors, scoreboards)
├── packages/        # External cocotb extensions (cocotbext-uart, cocotbext-i2c)
├── waves/           # Generated waveforms
└── logs/            # Test logs

Documentation

Backend Development Guide: Architecture and guide for GHDL/NVC/New Simulators.

Back to main documentation