Testing and Verification

Torii has a built-in simulation framework, as well as first-class formal verification support. As well as Python unittest integration for ease of setting up testing.

class torii.test.ToriiTestCase(*args, **kwargs)

Torii test case wrapper for pythons unittest library

This class wraps the TestCase class from the unittest module from the python standard lib. It has useful methods for testing and simulating Torii based gateware.

Attributes:

  • domains (tuple[tuple[str, float], …]) – The collection of clock domains and frequencies

  • out_dir (str) – The test output directory.

  • dut (Elaboratable) – The elaboratable to test.

  • dut_args (dict[str, Any]) – The initialization arguments for the elaboratable.

  • platform (MockPlatform, Any) – The platform passed to the Elaboratable DUT

property vcd_name: str

Return the name used to generate VCD files

clk_period(domain: str | None = None) → float

Returns the period of the clock on the given domain

run_sim(*, suffix: str | None = None) → None

Run the simulation

If the environment variable TORII_TEST_INHIBIT_VCD is set, then no VCDs will be generated.

Keyword Arguments:

suffix (str) – The option VCD test case suffix.

setUp() → None

Set up the simulator per test-case

init_dut()

Initialize and return the DUT

wait_for(time: float, domain: str | None = None)

Waits for the number time units.

Parameters:

time (float) – The unit of time to wait.

static pulse(sig: Signal, *, neg: bool = False, post_step: bool = True)

Pulse a given signal.

Pulse a given signal to 1 then 0, or if neg is set to True pulse from 1 to 0.

Parameters:

sig (Signal) – The signal to pulse.

Keyword Arguments:

  • neg (bool) – Inverts the pulse direction.

  • post_step (bool) – Insert additional simulation step after pulse.

static pulse_pos(sig: Signal, *, post_step: bool = True)

Inserts a positive pulse on the given signal

Parameters:

sig (Signal) – The signal to pulse.

Keyword Arguments:

post_step (bool) – Insert additional simulation step after pulse.

static pulse_neg(sig: Signal, *, post_step: bool = True)

Inserts a negative pulse on the given signal

Parameters:

sig (Signal) – The signal to pulse.

Keyword Arguments:

post_step (bool) – Insert additional simulation step after pulse.

static step(cycles: int)

Step simulator.

This advances the simulation by the given number of cycles.

Parameters:

cycles (int) – Number of cycles to step the simulator.

static settle(count: int = 1)

Settle simulator.

This advances the simulation by the given number of settles.

Parameters:

count (int) – Number of settles to invoke in the simulator.

static wait_until_high(strobe: Signal, *, timeout: int | None = None)

Run simulation until signal goes high.

Runs the simulation while checking for the positive edge of the strobe signal.

Will run until a positive edge is seen, or if timeout is set, will run for at most that many cycles.

This is the positive counterpart for the wait_until_low() method.

Parameters:

strobe (Signal) – The signal to check the strobe for.

Keyword Arguments:

timeout (int) – The max number of cycles to wait.

static wait_until_low(strobe: Signal, *, timeout: int | None = None)

Run simulation until signal goes low.

Runs the simulation while checking for the negative edge of the strobe signal.

Will run until a negative edge is seen, or if timeout is set, will run for at most that many cycles.

This is the negative counterpart for the wait_until_high() method.

Parameters:

strobe (Signal) – The signal to check the strobe for.

Keyword Arguments:

timeout (int) – The max number of cycles to wait.

static simulation(func)

Simulation test case decorator

Important

This must always be the top-most decorator due to how python decorator precedence works.

Parameters:

func – The decorated function.

static sync_domain(*, domain: str)

This decorator is used to annotate that the following function should be simulated in the specified synchronous domain.

It should be used in combination with ToriiTestCase.sim_test() to simulate a synchronous process.

Parameters:

domain (str) – The domain this process belongs to

static comb_domain(func)

This decorator is used to annotate that the following function should be simulated in the combinatorial domain.

It should be used in combination with ToriiTestCase.sim_test() to simulate a combinatorial process.