Package mars.simulator

Class Simulator

java.lang.Object
mars.simulator.Simulator
public class Simulator extends Object
Used to simulate the execution of an assembled MIPS program.
Author:
Pete Sanderson, August 2005

  • Field Details

    • UNLIMITED_SPEED

      public static final double UNLIMITED_SPEED
      Constant that represents unlimited run speed. Compare with return value of getRunSpeed() to determine if set to unlimited. At the unlimited setting, the GUI will not attempt to update register and memory contents as each instruction is executed. This is the only possible value for command-line use of Mars.
      See Also:

  • Method Details

    • getInstance

      public static Simulator getInstance()
      Returns the singleton instance of the MIPS simulator.
      Returns:
      The Simulator object in use.

    • isRunning

      public boolean isRunning()

    • getBackStepper

      public BackStepper getBackStepper()

    • getSystemIO

      public SystemIO getSystemIO()
      Obtain the associated SystemIO instance, which handles I/O-related syscall functionality.
      Returns:
      The system I/O handler.

    • reset

      public void reset()

    • getRunSpeed

      public double getRunSpeed()
      Get the current run speed of the simulator in instructions per second.
      Returns:
      The run speed, or UNLIMITED_SPEED if the run speed is unlimited.
      See Also:

    • isLimitingRunSpeed

      public boolean isLimitingRunSpeed()
      Determine whether the current run speed of the simulator is limited (that is, any value other than UNLIMITED_SPEED). When the run speed is limited, the simulator intentionally slows down execution to allow the GUI to track the program counter, memory accesses, register updates, etc.
      Returns:
      false if the current run speed is UNLIMITED_SPEED, or true otherwise.
      See Also:

    • setRunSpeed

      public void setRunSpeed(double runSpeed)
      Set the current run speed of the simulator in instructions per second.
      Parameters:
      runSpeed - The run speed, or UNLIMITED_SPEED to disable run speed limiting.
      Throws:
      IllegalArgumentException - Thrown if runSpeed is NaN or ≤ 0.

    • processJump

      public void processJump(int targetAddress)
      Schedule a jump in execution to another point in the program. If delayed branching is enabled, the actual jump will occur after the next instruction is executed.
      Parameters:
      targetAddress - The address of the instruction to jump to.

    • checkExternalInterruptDevice

      public Integer checkExternalInterruptDevice()
      Get the identifier of the memory-mapped I/O device which flagged an external interrupt, if any. Once this method is called, the external interrupt flag is reset.
      Returns:
      The device identifier, typically the address of the control register, or null if no interrupt was flagged.

    • raiseExternalInterrupt

      public void raiseExternalInterrupt(int device)
      Flag an external interrupt as a result of a memory-mapped I/O device.

      This method may be called from any thread.

      Parameters:
      device - The device identifier, typically the address of the control register.

    • changeState

      public void changeState(Runnable stateChanger)
      Modify program state used by the simulator (e.g. memory and registers) whenever is allowed by the simulator. If the simulator is not currently running, this change will occur immediately. On the other hand, if the simulator is running, this change will be queued and execute between instructions.

      If any thread other than the simulator needs to modify memory, registers, or some other program state, this method must be used for synchronization purposes!

      Parameters:
      stateChanger - The modification on program state, which will be performed asynchronously if needed.

    • flushStateChanges

      public void flushStateChanges()
      Perform any changes to program state from calls to changeState(Runnable) which are waiting to execute.

      Note: This method must be called from the simulator thread.

    • addGUIListener

      public void addGUIListener(SimulatorListener listener)
      Add a SimulatorListener whose callbacks will be executed on the GUI thread.
      Parameters:
      listener - The listener to add.
      See Also:

    • removeGUIListener

      public void removeGUIListener(SimulatorListener listener)
      Remove a SimulatorListener which was added via addGUIListener(SimulatorListener).
      Parameters:
      listener - The listener to remove.

    • addThreadListener

      public void addThreadListener(SimulatorListener listener)
      Add a SimulatorListener whose callbacks will be executed on the simulator thread.
      Parameters:
      listener - The listener to add.
      See Also:

    • removeThreadListener

      public void removeThreadListener(SimulatorListener listener)
      Remove a SimulatorListener which was added via addThreadListener(SimulatorListener).
      Parameters:
      listener - The listener to remove.

    • storeProgramArguments

      public void storeProgramArguments(List<String> arguments) throws SimulatorException
      Place any program arguments into MIPS memory and registers. Arguments are stored starting at highest word of non-kernel memory and working back toward runtime stack (there is a 4096 byte gap in between). The argument count (argc) and pointers to the arguments are stored on the runtime stack. The stack pointer register $sp is adjusted accordingly and $a0 is set to the argument count (argc), and $a1 is set to the stack address holding the first argument pointer (argv).
      Parameters:
      arguments - The list of program argument strings.
      Throws:
      SimulatorException - Thrown if a memory exception occurs while writing program arguments.

    • simulate

      public void simulate(int maxSteps, int[] breakpoints) throws SimulatorException
      Simulate execution of given MIPS program. It must have already been assembled.
      Parameters:
      maxSteps - Maximum number of steps to perform before returning false (0 or less means no max).
      breakpoints - Array of breakpoint program counter values. (Can be null.)
      Throws:
      SimulatorException - Thrown if an unhandled exception occurs in the program and MARS is running in the command line.

    • pause

      public void pause()
      Flag the simulator to stop due to pausing, unless it is already paused. Once it has stopped, SimulatorListener.simulatorPaused(SimulatorPauseEvent) will be called for all registered listeners.

    • terminate

      public void terminate()
      Flag the simulator to stop due to termination, even if it is currently paused. Once it has stopped, SimulatorListener.simulatorFinished(SimulatorFinishEvent) will be called for all registered listeners.

    • dispatchStartEvent

      public void dispatchStartEvent(int stepCount)
      Called when the simulator has started execution of the current program. Invokes SimulatorListener.simulatorStarted(SimulatorStartEvent) for all listeners.

    • dispatchPauseEvent

      public void dispatchPauseEvent(int stepCount, SimulatorPauseEvent.Reason reason)
      Called when the simulator has paused execution of the current program. Invokes SimulatorListener.simulatorPaused(SimulatorPauseEvent) for all listeners.

    • dispatchFinishEvent

      public void dispatchFinishEvent(SimulatorFinishEvent.Reason reason, SimulatorException exception)
      Called when the simulator has finished execution of the current program. Invokes SimulatorListener.simulatorFinished(SimulatorFinishEvent) for all listeners.

    • dispatchStepEvent

      public void dispatchStepEvent()
      Called when the simulator has finished executing an instruction, but only if the run speed is not unlimited. Invokes SimulatorListener.simulatorStepped() for all listeners.

      Note: For very fast run speeds, GUI listeners may not receive all step events. This is an intentional feature to prevent overloading of the GUI event queue.