CocoTB support#

The COCOTB command generates a ready-to-use Python script that integrates a Hog project with the cocotb hardware verification framework.

It reads the project’s Hog list files, resolves the full compile order (respecting library dependencies), and emits a self-contained Python file that calls cocotb_tools.runner to compile every HDL source and run a test against a chosen simulator.

Usage#

./Hog/Do COCOTB <project_name> [options]

<project_name> is the name of an existing Hog project (as listed by ./Hog/Do LIST).

Options#

Option

Description

-lib <path>

Path to a pre-compiled simulation library (e.g. SimulationLib/). When supplied, a -modelsimini flag pointing to <path>/modelsim.ini is added to every VHDL compilation unit. Can also be set via the HOG_SIMULATION_LIB_PATH environment variable.

-ext_path <path>

Absolute path for source files stored externally to the git repository.

-verbose

Enable verbose/debug output.

What It Does#

  1. Parses the project’s .src and .ext Hog list files to obtain the full source file set.

  2. Resolves the compile order using the Hog Hierarchy utility.

  3. Writes a Python script named cocotb_<project>.py in the repository root.

The generated script contains:

  • test_placeholder – an empty @cocotb.test() coroutine to be replaced with actual test logic.

  • build_libs(sim, build_dir) – iterates over every HDL source file in compile order and calls runner.build() for each one, setting:

    • hdl_library to the Hog library name for that file.

    • build_args to ["-2008"] for VHDL files (plus -modelsimini when a sim-lib path is provided).

    • build_args with +incdir+ entries for every directory containing .svh/.vh header files, for SystemVerilog/Verilog files.

  • run_test(sim, build_dir, toplevel) – calls runner.test() against the generated test module.

  • A __main__ block with argparse for --sim, --build-dir, and --toplevel.

Output#

A single Python file is created at:

<repo_root>/cocotb_<project>.py

Running the Generated Script#

python cocotb_<project>.py --sim questa --toplevel <your_top_entity>

Argument

Default

Description

--sim

questa

Simulator backend (e.g. questa, ghdl, icarus, verilator).

--build-dir

sim_build

Directory where build artefacts are written.

--toplevel

<toplevel>

Name of the HDL top-level entity/module to test.

Example#

# Generate the cocotb script for project MyFirmware
./Hog/Do COCOTB MyFirmware

# Optionally, point to a pre-compiled simulation library
./Hog/Do COCOTB MyFirmware -lib SimulationLib/

# Run the generated script with GHDL
python cocotb_MyFirmware.py --sim ghdl --toplevel my_top

Notes#

  • The generated script is a template: the placeholder test does nothing and must be replaced with meaningful verification logic.

  • The compile order emitted by the script mirrors Hog’s internal dependency resolution, so libraries are compiled before the design units that depend on them.

  • The COCOTB command runs entirely in tclsh without launching any IDE.

  • Supported HDL file extensions: .vhd, .vhdl, .v, .sv, .svh, .vh.