Bench: cocotb_utils#

This module contains the documentation for the cocotb utilities. Those are functions and classes that are used in the cocotb testbenches.

Library for utility functions used in the testbenches.

@author: Timothée Charrier

cocotb_utils.generate_coverage_report_questa(ucdb_file: Path, output_folder: Path) → None[source]#

Generate the coverage report in HTML format.

Parameters:

  • ucdb_file (Path) – The path to the UCDB file.

  • output_folder (Path) – The path to the output folder.

Raises:

  • FileNotFoundError – If the vcover executable is not found in the PATH.

  • RuntimeError – If the coverage report generation fails.

cocotb_utils.generate_coverage_report_verilator(dat_file: Path, output_folder: Path) → None[source]#

Generate the coverage report.

This function generates the coverage report using the verilator_coverage and genhtml commands. The coverage report is stored in the output_folder/coverage directory. Just open the index.html file in a browser to view the report.

Parameters:

  • dat_file (Path) – The path to the coverage.dat file.

  • output_folder (Path) – The simulation build directory

Raises:

  • FileNotFoundError – If the genhtml executable is not found in the PATH.

  • SystemExit – If the coverage report generation fails.

cocotb_utils.get_dut_state(dut: HierarchyObject) → dict[source]#

Get the state of the DUT at a given time.

Parameters:

dut (HierarchyObject) – The device under test (DUT).

Returns:

state – The state of the DUT ports.

Return type:

dict

Raises:

RuntimeError – If there is an error getting the value of a port.

Examples

>>> state = get_dut_state(dut)
>>> print(state)
cocotb_utils.init_hierarchy(dims: tuple[int, ...], *, bitwidth: int | None = None, use_random: bool = False) → list[source]#

Initialize a hierarchical data structure (1D, 2D, 3D, etc.).

Parameters:

  • dims (tuple[int, ...]) – Dimensions of the hierarchical structure (e.g., (4, 3, 2)).

  • bitwidth (int, optional) – Bitwidth for random signed values.

  • use_random (bool, optional) – If True, initialize with random values; otherwise, fill with zeroes.

Returns:

Hierarchical structure filled as specified.

Return type:

list

async cocotb_utils.initialize_dut(dut: HierarchyObject, inputs: dict, outputs: dict, *, clock_name: str = 'clock', reset_name: str = 'reset_n', sys_enable_name: str = 'i_sys_enable', clock_period_ns: int = 10, reset_high: int = 0, verbose: bool = True) → None[source]#

Initialize the DUT with default values.

Parameters:

  • dut (HierarchyObject) – The device under test (DUT).

  • inputs (dict) – A dictionary containing the input names and values.

  • outputs (dict) – A dictionary containing the output names and expected values.

  • clock_name (str, optional) – Name of the clock signal (default is “clock”).

  • reset_name (str, optional) – Name of the reset signal (default is “reset_n”).

  • sys_enable_name (str, optional) – Name of the sys_enable signal (default is “i_sys_enable”).

  • clock_period_ns (int, optional) – Clock period in nanoseconds (default is 10).

  • reset_high (int, optional) – Indicates if the reset signal is active high (1) or active low (0). By default, the reset signal is active low (0).

  • verbose (bool, optional) – If True, logs the initialization operation (default is True).

Raises:

RuntimeError – If there is an error initializing the DUT.

Examples

>>> inputs = {"i_data": 0, "i_valid": 0}
>>> outputs = {"o_data": 0, "o_valid": 0}
>>> await initialize_dut(dut, inputs, outputs)
cocotb_utils.log_generics(dut: HierarchyObject, generics: dict[str, int]) → None[source]#

Log the generic parameters from the DUT in a table format.

Parameters:

  • dut (HierarchyObject) – The device under test (DUT).

  • generics (dict) – A dictionary of generic parameters.

cocotb_utils.random_signed_value(bitwidth: int) → int[source]#

Generate a random signed value within the given bitwidth.

Parameters:

bitwidth (int) – The bitwidth of the signed value.

Returns:

A random signed integer within the range of the given bitwidth.

Return type:

int

Raises:

ValueError – If the bitwidth is not a positive integer.

async cocotb_utils.reset_dut(dut: HierarchyObject, *, clock_name: str = 'clock', reset_name: str = 'reset_n', num_cycles: int = 5, reset_high: int = 0, verbose: bool = True) → None[source]#

Reset the DUT.

This function asserts the reset signal for ‘num_cycles’ and then deasserts it.

Parameters:

  • dut (HierarchyObject) – The device under test.

  • clock_name (str, optional) – Name of the clock signal (default is “clock”).

  • reset_name (str, optional) – Name of the reset signal (default is “reset_n”).

  • num_cycles (int, optional) – Number of clock cycles to assert the reset signal (default is 5).

  • reset_high (int, optional) – Indicates if the reset signal is active high (1) or active low (0). By default, the reset signal is active low (0).

  • verbose (bool, optional) – If True, logs the reset operation (default is True).

Raises:

  • ValueError – If the reset_high value is not 0 or 1.

  • AttributeError – If the clock or reset signal is not found in the DUT.

  • RuntimeError – If there is an error resetting the DUT.

async cocotb_utils.setup_clock(dut: HierarchyObject, *, clock_name: str = 'clock', period_ns: int = 10, verbose: bool = True) → None[source]#

Initialize and start the clock for the DUT.

Parameters:

  • dut (HierarchyObject) – The Device Under Test (DUT).

  • clock_name (str, optional) – Name of the clock signal (default is “clock”).

  • period_ns (int) – Clock period in nanoseconds (default is 10).

  • verbose (bool, optional) – If True, logs the clock operation (default is True).

Raises:

  • AttributeError – If the clock signal is not found in the DUT.

  • RuntimeError – If there is an error setting up the clock.

async cocotb_utils.sys_enable_dut(dut: HierarchyObject, *, clock_name: str = 'clock', sys_enable_name: str = 'i_sys_enable', verbose: bool = True) → None[source]#

Enable the DUT.

Parameters:

  • dut (HierarchyObject) – The device under test.

  • clock_name (str, optional) – Name of the clock signal (default is “clock”).

  • sys_enable_name (str, optional) – Name of the sys_enable signal (default is “i_sys_enable”).

  • verbose (bool, optional) – If True, logs the enable operation (default is True).

Raises:

  • AttributeError – If the sys_enable or clock signal is not found in the DUT.

  • AttributeError – If the DUT does not have a sys_enable signal.

  • RuntimeError – If there is an error enabling the DUT.

async cocotb_utils.toggle_signal(dut: HierarchyObject, signal_dict: dict, *, clock_name: str = 'clock', verbose: bool = True) → None[source]#

Toggle a signal between high and low values.

Parameters:

  • dut (HierarchyObject) – The device under test (DUT).

  • signal_dict (dict) – A dictionary containing the signal name and value. If the value is 1, the signal is toggled to 0; otherwise, it is toggled to 1.

  • clock_name (str, optional) – Name of the clock signal (default is “clock”).

  • verbose (bool, optional) – If True, logs the signal toggling operation (default is True).

Raises:

  • AttributeError – If the clock signal or required signal is not found in the DUT.

  • AttributeError – If the DUT does not have the required signal in the signal_dict.

  • RuntimeError – If there is an error toggling the signal.

Examples

>>> signal_dict = {"i_valid": 0, "i_ready": 0}
>>> await toggle_signal(dut, signal_dict, clock_name="clock", verbose=True)