byucc.jhdl.base
Interface SimulatorCallback

All Known Implementing Classes:

ClassInfo, MemoryViewer, MemoryViewerPanel, SchematicCanvas, SimIndicatorComponent, TboneObserver, WatchInterface, WavesWireManager

public interface SimulatorCallback

This interface is used by any object that wants to receive callbacks from the simulator. Such callbacks could be used by GUI components to display the state of the system or by less visible components to monitor the state of the simulation. JHDL cells can also implement this interface to perform self-checking or debugging. Such callbacks are extrememly powerful and can be used to significantly improve the verification process of JHDL circuits.

The Observable interface is being deprecated and should be replaced by SimulatorCallback. While the Observable interface does the same thing as this interface, is not a very good name for this interface (this interface does not represent Observables but Observers). Also, the names used by both Observer and Observable are not very clear and there are name clashes with Swing (i.e. update). This interface replaces the two duplicate methods for receiving callbacs from the simulator. While the Observable interface will not be initially removed from JHDL, it will likely be removed in a near future release.

A related simulation callback interface is the Initializeable interface. Use this interface for performing a one-time initialization of a callback. Unlike the initilize callback method, the simulatorReset method is called every time the simulator is reset.

Registering SimulatorCallbacks

SimulatorCallbacks can be registered with the simulator in the following ways:

1. If a Cell implements the SimulatorCallback interface, it will automatically be registered with the simulator. When new cells are added to a HWSystem, those that implement the interface are registered by default. Note that this automatic registration only works with Cell objects and no other object type (i.e. GUIs, etc.). Cell objects do not require any registration call.
2. For non-Cell objects, the SimulatorCallback interface can be registered with the simulator by calling the addSimulatorCallback() method within a HWSystem
3. Another method for adding SimulatorCallbacks to the HWSystem is to call the addSimulatorCallback() method on a Node reference. It is often more convenient to use a Node reference rather than a HWSystem reference.

SimulatorCallbacks can also be unregistered with the simulator in the following ways:

1. SimulatorCallback interfaces can be unregistered with the simulator by calling the removeSimulatorCallback() method within a HWSystem

Author:

Mike Wirthlin

Method Summary

void	simulatorRefresh(int cycle, int phase) This method is called after each simulation run.
void	simulatorReset() This method will be called after the simulation has been reset.
void	simulatorUpdate(int cycle, int phase) This method is called after each simulation event.

Method Detail

simulatorRefresh

public void simulatorRefresh(int cycle,
                             int phase)

This method is called after each simulation run. A simulation run is a multiple clock/step execution issued by a testbench or jab. For example, if the user types 'cycle 50', this callback method will be called after the completed simulation of all 50 clock cycles. Unlike the simulatorUpdate method, this method will not be called on each simulation event. This method is useful for GUIs or display widgets that only need to be updated once the simulaton has paused.

Parameters:

cycle - The current cycle number of the simulator. This value is the same as the value generated by the call HWSystem.getTotalClockCount().

phase - The current phase of the simulator. This value is the same as the value generated by the call HWSystem.getCurrentStepCount().

simulatorUpdate

public void simulatorUpdate(int cycle,
                            int phase)

This method is called after each simulation event. The granularity of the event is determined by the specific Simulator within the simulate() method of the Simulator. For the single-clock simulator, this corresponds to each cycle of simulation. For the multi-clock simulator, this corresponds to each step in the clock schedule of the simulator.

Parameters:

cycle - The current cycle number of the simulator. This value is the same as the value generated by the call HWSystem.getTotalClockCount().

phase - The current phase of the simulator. This value is the same as the value generated by the call HWSystem.getCurrentStepCount().

simulatorReset

public void simulatorReset()

This method will be called after the simulation has been reset. Unlike the initialize method of the Initializeable interface, this method is called after every simulator reset. This method can be used to reset variables associated with watching the progress of a simulation. Note that the cycle and phase number is reset to zero before this call is made.