Simulation and Testing

Simulation

class pyrtl.simulation.Simulation(tracer=True, register_value_map=None, memory_value_map=None, default_value=0, block=None)

Bases: object

A class for simulating blocks of logic step by step.

In addition to the functions methods listed below, it is sometimes useful to reach into this class and access internal state directly. Of particular usefulness are:

  • .tracer: stores the SimulationTrace in which results are stored
  • .value: a map from every signal in the block to its current simulation value
  • .regvalue: a map from register to its value on the next tick
  • .memvalue: a map from memid to a dictionary of address: value
__init__(tracer=True, register_value_map=None, memory_value_map=None, default_value=0, block=None)

Creates a new circuit simulator

Parameters:
  • tracer – an instance of SimulationTrace used to store execution results. Defaults to a new SimulationTrace with no params passed to it. If None is passed, no tracer is instantiated (which is good for long running simulations). If the default (true) is passed, Simulation will create a new tracer automatically which can be referenced by the member variable .tracer
  • register_value_map – Defines the initial value for the roms specified. Format: {Register: value}.
  • memory_value_map – Defines initial values for many addresses in a single or multiple memory. Format: {Memory: {address: Value}}. Memory is a memory block, address is the address of a value
  • default_value – is the value that all unspecified registers and memories will initialize to. If no default_value is specified, it will use the value stored in the object (default to 0)
  • block – the hardware block to be traced (which might be of type PostSynthesisBlock). defaults to the working block

Warning: Simulation initializes some things when called with __init__, so changing items in the block for Simulation will likely break the simulation.

step(provided_inputs)

Take the simulation forward one cycle

Parameters:provided_inputs – a dictionary mapping wirevectors to their values for this step

All input wires must be in the provided_inputs in order for the simulation to accept these values

Example: if we have inputs named ‘a’ and ‘x’, we can call: sim.step({‘a’: 1, ‘x’: 23}) to simulate a cycle with values 1 and 23 respectively

inspect(w)

Get the value of a wirevector in the last simulation cycle.

Parameters:w – the name of the WireVector to inspect (passing in a WireVector instead of a name is deprecated)
Returns:value of w in the current step of simulation

Will throw KeyError if w does not exist in the simulation.

inspect_mem(mem)

Get the values in a map during the current simulation cycle.

Parameters:mem – the memory to inspect
Returns:{address: value}

Note that this returns the current memory state. Modifying the dictonary will also modify the state in the simulator

Fast Simulation

class pyrtl.simulation.FastSimulation(register_value_map=None, memory_value_map=None, default_value=0, tracer=True, block=None, code_file=None)

Bases: object

A class for running JIT implementations of blocks.

__init__(register_value_map=None, memory_value_map=None, default_value=0, tracer=True, block=None, code_file=None)

Instantiates a Fast Simulation instance.

The interface for FastSimulation and Simulation should be almost identical. In addition to the Simualtion arguments, FastSimulation additional takes:

Parameters:code_file – The file in which to store a copy of the generated

python code. Defaults to no code being stored.

Look at Simulation.__init__ for descriptions for the other parameters

This builds the Fast Simulation compiled Python code, so all changes to the circuit after calling this function will not be reflected in the simulation

step(provided_inputs)

Run the simulation for a cycle

Parameters:provided_inputs – a dictionary mapping WireVectors (or their names) to their values for this step eg: {wire: 3, “wire_name”: 17}
inspect(w)

Get the value of a wirevector in the last simulation cycle.

Parameters:w – the name of the WireVector to inspect (passing in a WireVector instead of a name is deprecated)
Returns:value of w in the current step of simulation

Will throw KeyError if w is not being tracked in the simulation.

inspect_mem(mem)

Get the values in a map during the current simulation cycle.

Parameters:mem – the memory to inspect
Returns:{address: value}

Note that this returns the current memory state. Modifying the dictonary will also modify the state in the simulator

Simulation Trace

class pyrtl.simulation.SimulationTrace(wires_to_track=None, block=None)

Bases: object

Storage and presentation of simulation waveforms.

__init__(wires_to_track=None, block=None)

Creates a new Simulation Trace

Parameters:
  • wires_to_track – The wires that the tracer should track
  • block
add_step(value_map)

Add the values in value_map to the end of the trace.

add_fast_step(fastsim)

Add the fastsim context to the trace.

print_trace(file=<open file '<stdout>', mode 'w'>, base=10, compact=False)

Prints a list of wires and their current values. :param int base: the base the values are to be printed in :param bool compact: whether to omit spaces in output lines

print_vcd(file=<open file '<stdout>', mode 'w'>, include_clock=False)

Print the trace out as a VCD File for use in other tools.

Parameters:
  • file – file to open and output vcd dump to.
  • include_clock – boolean specifying if the implicit clk should be included.

Dumps the current trace to file as a “value change dump” file. The file parameter defaults to _stdout_ and the include_clock defaults to True.

Examples

sim_trace.print_vcd()
sim_trace.print_vcd("my_waveform.vcd", include_clock=False)
render_trace(trace_list=None, file=<open file '<stdout>', mode 'w'>, render_cls=<class 'pyrtl.simulation.AsciiWaveRenderer'>, symbol_len=5, segment_size=5, segment_delim=u' ', extra_line=True)

Render the trace to a file using unicode and ASCII escape sequences.

Parameters:
  • trace_list – A list of signals to be output in the specified order.
  • file – The place to write output, default to stdout.
  • render_cls – A class that translates traces into output bytes.
  • symbol_len – The “length” of each rendered cycle in characters.
  • segment_size – Traces are broken in the segments of this number of cycles.
  • segment_delim – The character to be output between segments.
  • extra_line – A Boolean to determin if we should print a blank line between signals.

The resulting output can be viewed directly on the terminal or looked at with “more” or “less -R” which both should handle the ASCII escape sequences used in rendering. render_trace takes the following optional arguments.