elasticai.creator.testing

Package Contents

Classes

CocotbTestFixture	Run cocotb via pytest, inject parameters to be available before and during test execution.
GHDLSimulator	Run a simulation tool for a given top_design and save whatever is written to stdout for subsequent inspection.
Testbench
SimulatedLayer

Functions

run_cocotb_sim	Function for running Verilog/VHDL Simulation using COCOTB environment
run_cocotb_sim_for_src_dir	Function for running Verilog/VHDL Simulation using COCOTB environment
check_cocotb_test_result
build_report_folder_and_testdata	Building the test/simulation folder which contains the test data and hardware design for testing in cocotb
read_testdata	Reading the data as testpattern in the cocotb testbench
parse_report
cocotb_test_fixture	Yields the setup CocotbTestFixture and performs necessary clean up after the test run.
eai_testbench	Intended usage:

API

elasticai.creator.testing.run_cocotb_sim(src_files: collections.abc.Iterable[str] | collections.abc.Iterable[pathlib.Path], top_module_name: str, cocotb_test_module: str, defines: dict[str, Any] | collections.abc.Callable[[], dict[str, Any]] = lambda : ..., params: dict[str, Any] | collections.abc.Callable[[], dict[str, Any]] = lambda : ..., timescale: tuple[str, str] = ('1ps', '1fs'), en_debug_mode: bool = True, waveform_save_dst: str = '', build_sim_dir: str | pathlib.Path | None = None) → pathlib.Path

Function for running Verilog/VHDL Simulation using COCOTB environment

Parameters:

• src_files – List with source files of each used Verilog/VHDL file

• top_module_name – Name of the top module (from file)

• cocotb_test_module – Fully qualified name of python module containing cotName of the cocotb testbench in Python

• defines – Dictionary of parameters to pass to the module [key: value, …] - usable only in Verilog

• params – Dictionary of parameters to pass to the module [key: value, …] - verilog parameters or vhdl generics

• timescale – Tuple with Timescale value for simulation (step, accuracy)

• en_debug_mode – Enable debug mode

• waveform_save_dst – Path to the destination folder for saving waveform file

Returns:

Path to folder which includes waveform file [Default: simulation output folder]

class elasticai.creator.testing.CocotbTestFixture(test_fn: collections.abc.Callable, *args: float | int | str, **kwargs: float | int | str)

Run cocotb via pytest, inject parameters to be available before and during test execution.

The fixture will inspect the requesting test function to assume some default values and perform a little bit of setup. Namely this is

• Use the test function name to determine the dut top module name and the name of its containing source file. These can be overriden inside the test function using .set_top_module_name() and .set_srcs(). The default name will be derived by stripping the test_ prefix from the test function name. The implementation will try to find a vhdl or verilog file under ../{vhdl, verilog}/<name>.{vhd, v}. Vhdl will take precedence. If no file is found, the initial srcs list will be left empty without raising an exception.

• It will create a folder to contain test artifacts including waveforms, xml result, testdata json and compiled simulation object files. To avoid collisions, the name of the folder will be derived from the fully qualified test function name (replacing . by /) and the parameter list provided via pytest parametrization.

  The fixture assumes the test resolves package resources itself (e.g. via get_file_from_package). It will keep open the files whose paths are passed to set_srcs()/add_srcs() while run executes, but you must keep a surrounding with in the test so the package helper holds the resource alive during the simulation.

• If you need to generate hdl sources prior to running testbenches and want to store them with the rest of the testing artifacts, you can retrieve the automatically determined folder via the .get_artifact_dir() method. This allows you to store the sources there and pass the resulting paths to the fixture using eg. .add_srcs.

This is not intended to be used directly. Request cocotb_test_fixture as a pytest fixture instead.

Initialization

setup()

teardown()

get_artifact_dir() → pathlib.Path

write(data: dict[str, Any]) → None

set_top_module_name(top_module_name: str) → None

set_srcs(srcs: collections.abc.Iterable[str | pathlib.Path])

add_srcs(*srcs: str | pathlib.Path) → None

set_timescale(scale: tuple[str, str]) → None

run(params, defines)

elasticai.creator.testing.run_cocotb_sim_for_src_dir(src_files: collections.abc.Iterable[str] | collections.abc.Iterable[pathlib.Path], top_module_name: str, cocotb_test_module: str, path2src: str = '', defines: dict | collections.abc.Callable[[], dict] = lambda : ..., params: dict | collections.abc.Callable[[], dict] = lambda : ..., timescale: tuple[str, str] = ('1ps', '1fs'), en_debug_mode: bool = True, waveform_save_dst: str = '') → pathlib.Path

Function for running Verilog/VHDL Simulation using COCOTB environment

Parameters:

• src_files – List with source files of each used Verilog/VHDL file

• top_module_name – Name of the top module (from file)

• cocotb_test_module – Fully qualified name of python module containing cotName of the cocotb testbench in Python

• path2src – Path to the folder in which all src files are available for testing

• defines – Dictionary of parameters to pass to the module [key: value, …] - usable only in Verilog

• params – Dictionary of parameters to pass to the module [key: value, …] - value will be ignored

• timescale – Tuple with Timescale value for simulation (step, accuracy)

• en_debug_mode – Enable debug mode

• waveform_save_dst – Path to the destination folder for saving waveform file

Returns:

Path to folder which includes waveform file [Default: simulation output folder]

elasticai.creator.testing.check_cocotb_test_result(result_folder_cocotb: str = 'build_sim') → bool

elasticai.creator.testing.build_report_folder_and_testdata(dut_name: str, testdata: dict) → pathlib.Path

Building the test/simulation folder which contains the test data and hardware design for testing in cocotb

Parameters:

• dut_name – The name of the Top Module

• testdata – Dictionary with test data/params data

Returns:

Path to the report folder containing hardware design and testpattern data

elasticai.creator.testing.read_testdata(dut_name: str) → dict

Reading the data as testpattern in the cocotb testbench

Parameters:

dut_name – The name of the Top Module DUT in the cocotb testbench (using dut._name)

Returns:

Dictionary with testpattern for testing the DUT

class elasticai.creator.testing.GHDLSimulator(workdir, top_design_name)

Run a simulation tool for a given top_design and save whatever is written to stdout for subsequent inspection.

This runner uses the GHDL tool. The parsed content has the following keys: `(“source”, “line”, “column”, “time”, “type”, “content”)’

Will raise a SimulationError in case any of the calls to ghdl in the steps initialize or run fails. Args: workdir: typically the path to your build root, this is where we will look for vhd files

Initialization

add_generic(**kwargs)

initialize()

Call this function once before calling run() and on every file change.

run()

Runs the simulation and saves whatever the tool wrote to stdout. You’re supposed to call initialize once, before calling run.

getReportedContent() → list[str]

Strips any information that the simulation tool added automatically to the output to return only the information that was printed to stdout via VHDL/Verilog statements.

getFullReport() → list[dict]

Parses the output from the simulation tool, to provide a more structured representation. The exact content depends on the simulation tool.

getRawResult() → str

Returns the raw stdout output as written by the simulation tool.

elasticai.creator.testing.parse_report(text: str)

class elasticai.creator.testing.Testbench

abstract property name: str

abstractmethod save_to(destination: elasticai.creator.file_generation.savable.Path) → None

abstractmethod prepare_inputs(*args: Any, **kwargs: Any) → Any

abstractmethod parse_reported_content(*args, **kwargs: Any) → Any

class elasticai.creator.testing.SimulatedLayer(testbench: elasticai.creator.testing.simulated_layer.Testbench, simulator_constructor, working_dir: str | pathlib.Path)

Initialization

__call__(inputs: Any) → Any

elasticai.creator.testing.cocotb_test_fixture(request) → collections.abc.Iterator[elasticai.creator.testing.cocotb_pytest.CocotbTestFixture]

Yields the setup CocotbTestFixture and performs necessary clean up after the test run.

To use the fixture either place add the line

pytest_plugins = "elasticai.creator.testing.cocotb_pytest"

to either a conftest.py in the test directory tree or in the test module.

For more information see the documentation of CocotbTestFixture

elasticai.creator.testing.eai_testbench(fn)

Intended usage:

@cocotb.test()
@eai_testbench
async def my_testbench_for_input_buffer(dut, x, input_data):
  dut.d_in = x

and

@pytest.mark.parametrize("x", [1, 2, 3])
def test_input_buffer(cocotb_test_fixture, x):
  cocotb_test_fixture.write({"input_data": "hello world"})
  cocotb_test_fixture.run()

The example will assume your toplevel module is "input_buffer" and it’s source file lives in a sibling folder of the test folder that contains the pytest test function. It will create a unique subdirectory under build_test that matches the path to the module containing the testbench definition and pytest test function (both need to live in the same module). This prevents test A overriding the artifacts of test B. The name of the subdirectory will be derived from the parameters passed via the parametrize pytest marker and the top module name. In this example this results in folders: input_buffer_test_input_buffer_x_1, input_buffer_test_input_buffer_x_2, input_buffer_test_input_buffer_x_3.