Simulation

class torii.sim.Active

Todo

Document Me

class torii.sim.Delay(interval: int | float | None = None) → None

Todo

Document Me

class torii.sim.Passive

Todo

Document Me

class torii.sim.Settle

Micro-steps the simulation until just before the next clock cycle would start

class torii.sim.Simulator(fragment: Fragment | Elaboratable, *, engine: type[BaseEngine] | Literal['pysim', 'wasm'] = 'pysim') → None

Todo

Document Me

add_clock(period: float, *, phase: float | None = None, domain: str | ClockDomain = 'sync', if_exists: bool = False) → None

Add a clock process that drives the clock signal of domain at a 50% duty cycle.

Parameters:

  • period (float) – Clock period. The process will toggle the domain clock signal every period / 2 seconds.

  • phase (None or float) – Clock phase. The process will wait phase seconds before the first clock transition. If not specified, defaults to period / 2.

  • domain (str or ClockDomain) – Driven clock domain. If specified as a string, the domain with that name is looked up in the root fragment of the simulation.

  • if_exists (bool) – If False (the default), raise an error if the driven domain is specified as a string and the root fragment does not have such a domain. If True, do nothing in this case.

add_process(process: Callable[[], Generator] | Callable[[], Coroutine]) → None

Add a process that runs purely in the combinatorial domain.

Parameters:

process (collections.abc.Callable[[], Generator] | collections.abc.Callable[[], Coroutine]) – The simulation process to add.

add_sync_process(process: Callable[[], Generator] | Callable[[], Coroutine], *, domain: str | ClockDomain = 'sync') → None

Add a process that runs synchronously on a given clock domain.

Parameters:
advance() → bool

Advance the simulation.

Run every process and commit changes until a fixed point is reached, then advance time to the closest deadline (if any). If there is an unstable combinatorial loop, this function will never return.

Return type:

bool

Returns:

bool – True if there are any active simulation processes, otherwise False.

reset() → None

Reset the simulation.

Assign the reset value to every signal in the simulation, and restart every user process.

run() → None

Run the simulation while any processes are active.

Processes added with add_process() and add_sync_process() are initially active, and may change their status using the yield Passive() and yield Active() commands. Processes compiled from HDL and added with add_clock() are always passive.

run_until(deadline: int, *, run_passive: bool = False) → None

Run the simulation until it advances to deadline.

If run_passive is False, the simulation also stops when there are no active processes, similar to run(). Otherwise, the simulation will stop only after it advances to or past deadline.

Danger

If the simulation stops advancing, this function will never return.

Parameters:

  • deadline (int) – The number of simulation steps to set the deadline at.

  • run_passive (bool) – If True the simulation will only stop once deadline is reached or passed.

write_vcd(vcd_file: IO | str | None, gtkw_file: IO | str | None = None, *, traces: Iterable[Signal] = ()) → ContextManager[None]

Write waveforms to a Value Change Dump file, optionally populating a GTKWave save file.

This method returns a context manager. It can be used as:

sim = Simulator(frag)
sim.add_clock(1e-6)
with sim.write_vcd('dump.vcd", "dump.gtkw'):
        sim.run_until(1e-3)
Parameters:
Return type:

ContextManager[None]

class torii.sim.Tick(domain: str | ClockDomain = 'sync') → None

Runs only the transition from high->low->high but does not progress execution further than that.

Warning

This can cause things to appear out-of-step.