avrora.sim
Class Simulator

java.lang.Object
  avrora.sim.Simulator

public class Simulator

extends java.lang.Object

The Simulator class implements a full processor simulator for the AVR instruction set. It is the base class of specific implementations that implement processor-specific behavior.

See Also:

Program, Instr, BaseInterpreter

Nested Class Summary

class	Simulator.ClockCycleTimeout The InstructionCountTimeout class is a probe that simply counts down and throws an exception when the count reaches zero.
static interface	Simulator.Event The Simulator.Event interface represents an event that is fired when a timed event occurs within the simulator.
static interface	Simulator.ExceptionWatch The Simulator.ExceptionWatch interface allows for monitoring of exceptional conditions in the machine state.
static interface	Simulator.InterruptProbe The InterruptProbe interface represents a programmer-defined probe that can be inserted on an interrupt.
static interface	Simulator.IORWatch The IORWatch interface represents a user probe that is fired when a watchpoint detects an access to an IO register where the watch has been inserted.
class	Simulator.Printer The Simulator.Printer class is a printer that is tied to a specific Simulator instance.
static interface	Simulator.Probe The Simulator.Probe interface represents a programmer-defined probe that can be inserted at a particular instruction in the program. or at every instruction.
static interface	Simulator.Watch The Watch interface represents a user watch that is fired when a watchpoint detects an access to an address where this watch has been inserted.

Field Summary

protected MainClock	clock The clock field stores a reference to the MainClock instance that tracks the clock cycles that have passed for this simulator.
protected InterpreterFactory	factory The factory field stores a reference to the InterpreterFactory which should be used to build an interpreter for this simulator.
protected int	id The id field stores a unique identifier used to differentiate this simulator from others that might be running in the same simulation.
protected BaseInterpreter	interpreter The interpreter field stores a reference to the instruction set interpreter.
protected Microcontroller	microcontroller The microcontroller field stores a reference to the microcontroller being simulated.
protected Program	program The program field allows descendants of the Simulator class to access the program that is currently loaded in the simulator.

Constructor Summary

Simulator(int i, InterpreterFactory f, Microcontroller mcu, Program p)
The constructor creates the internal data structures and initial state of the processor.

Method Summary

void	delay(long cycles) The delay() method introduces a delay in the execution of the instructions of the program.
void	forceInterrupt(int num) The forceInterrupt() method forces the simulator to post the specified interrupt regardless of the normal source of the interrupt.
MainClock	getClock() The getClock() method gets a reference to the Clock that this simulator is driving.
int	getID() The getID() method simply returns this node's unique ID.
BaseInterpreter	getInterpreter() The getInterpreter() method returns the interpreter that is currently attached to this simulator.
Microcontroller	getMicrocontroller() The getMicrocontroller() method gets a reference to the microcontroller being simulated.
Simulator.Printer	getPrinter(java.lang.String c) The getPrinter() method returns a Simulator.Printer instance for the named verbose channel.
Program	getProgram() The getProgram() method gets a reference to the program that has been loaded onto this simulator.
State	getState() The getState() retrieves a reference to the current state of the simulation, including the values of all registers, the SRAM, the IO register, the program memory, program counter, etc.
void	insertEvent(Simulator.Event e, long cycles) The insertEvent() method inserts an event into the event queue of the simulator with the specified delay in clock cycles.
void	insertExceptionWatch(Simulator.ExceptionWatch watch) The insertExceptionWatch() method registers an ExceptionWatch instance.
void	insertInterruptProbe(Simulator.InterruptProbe p, int inum) The insertInterruptProbe() method inserts an interrupt probe on an interrupt.
void	insertIORWatch(Simulator.IORWatch p, int ioreg_num) The insertIORWatch() method allows an IO register watch to be inserted on an IO register.
void	insertProbe(Simulator.Probe p) The insertProbe() method allows a probe to be inserted that is executed before and after every instruction that is executed by the simulator
void	insertProbe(Simulator.Probe p, int addr) The insertProbe() method allows a probe to be inserted at a particular address in the program that corresponds to an instruction.
void	insertTimeout(long cycles) The insertTimeout() method inserts an event into the event queue of the simulator that causes it to stop execution and throw a Simulator.TimeoutException when the specified number of clock cycles have expired.
void	insertWatch(Simulator.Watch p, int data_addr) The insertWatch() method allows a watch to be inserted at a memory location.
void	removeEvent(Simulator.Event e) The removeEvent() method removes an event from the event queue of the simulator.
void	removeInterruptProbe(Simulator.InterruptProbe p, int inum) The removeInterruptProbe() method removes an interrupt probe from an interrupt.
void	removeIORWatch(Simulator.IORWatch p, int ioreg_num) The removeIORWatch() removes an IO register watch from the given register.
void	removeProbe(Simulator.Probe b) The removeProbe() method removes a probe from the global probe table (the probes executed before and after every instruction).
void	removeProbe(Simulator.Probe p, int addr) The removeProbe() method removes a probe from the instruction at the specified the address.
void	removeWatch(Simulator.Watch p, int data_addr) The removeWatch() method removes a given watch from the memory location.
void	start() The start() method begins the simulation.
int	step() The step() method steps the simulation one instruction or cycle.
void	stop() The stop() method stops the simulation if it is running.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

program

protected final Program program

The program field allows descendants of the Simulator class to access the program that is currently loaded in the simulator.

microcontroller

protected final Microcontroller microcontroller

The microcontroller field stores a reference to the microcontroller being simulated.

interpreter

protected BaseInterpreter interpreter

The interpreter field stores a reference to the instruction set interpreter.

clock

protected MainClock clock

The clock field stores a reference to the MainClock instance that tracks the clock cycles that have passed for this simulator.

id

protected final int id

The id field stores a unique identifier used to differentiate this simulator from others that might be running in the same simulation.

factory

protected final InterpreterFactory factory

The factory field stores a reference to the InterpreterFactory which should be used to build an interpreter for this simulator. This interpreter factory will create an interpreter with the correct options that were specified on the command line.

Constructor Detail

Simulator

public Simulator(int i,
                 InterpreterFactory f,
                 Microcontroller mcu,
                 Program p)

The constructor creates the internal data structures and initial state of the processor. It constructs an instance of the simulator that is ready to have devices attached, IO registers probed, and probes and events inserted. Users should not create Simulator instances directly, but instead should get an instance of the appropriate processor and load the program into it.

Parameters:

p - the program to load into the simulator

Method Detail

getPrinter

public Simulator.Printer getPrinter(java.lang.String c)

The getPrinter() method returns a Simulator.Printer instance for the named verbose channel. The verbose channel is either enabled or disabled.

Parameters:

c - the name of the verbose channel

Returns:

a Simulator.Printer instance for this channel tied to this Simulator instance

getMicrocontroller

public Microcontroller getMicrocontroller()

The getMicrocontroller() method gets a reference to the microcontroller being simulated.

Returns:

a reference to the microcontroller being simulated

getProgram

public Program getProgram()

The getProgram() method gets a reference to the program that has been loaded onto this simulator.

Returns:

a reference to the Program instance representing the program loaded onto this Simulator object

getClock

public MainClock getClock()

The getClock() method gets a reference to the Clock that this simulator is driving.

Returns:

a reference to the clock for this simulator

getID

public int getID()

The getID() method simply returns this node's unique ID.

Returns:

the unique ID of this node

getInterpreter

public BaseInterpreter getInterpreter()

The getInterpreter() method returns the interpreter that is currently attached to this simulator.

Returns:

the current interpreter

getState

public State getState()

The getState() retrieves a reference to the current state of the simulation, including the values of all registers, the SRAM, the IO register, the program memory, program counter, etc. This state is mutable.

Returns:

a reference to the current state of the simulation

start

public void start()

The start() method begins the simulation. It causes the simulator to invoke a runLoop that executes instructions, firing probes and events as it executes. The start() method returns normally when the break AVR instruction is executed, when a BreakPointException is thrown, when a TimeoutException is thrown, or when the stop() method on this simulator instance is called.

step

public int step()

The step() method steps the simulation one instruction or cycle.

Returns:

the number of cycles advanced; 1 in the case of sleeping, delaying, 1 in the case of handling an interrupt, and for all other multi-cycle instructions, the number of cycles consumed by executing the instruction

stop

public void stop()

The stop() method stops the simulation if it is running. This method can be called from within a probe or event or from another thread.

insertProbe

public void insertProbe(Simulator.Probe p)

The insertProbe() method allows a probe to be inserted that is executed before and after every instruction that is executed by the simulator

Parameters:

p - the probe to insert

insertProbe

public void insertProbe(Simulator.Probe p,
                        int addr)

The insertProbe() method allows a probe to be inserted at a particular address in the program that corresponds to an instruction. The probe is then fired before and after that particular instruction is executed.

Parameters:

p - the probe to insert

addr - the address at which to insert the probe

removeProbe

public void removeProbe(Simulator.Probe b)

The removeProbe() method removes a probe from the global probe table (the probes executed before and after every instruction). The comparison used is reference equality, not .equals().

Parameters:

b - the probe to remove

removeProbe

public void removeProbe(Simulator.Probe p,
                        int addr)

The removeProbe() method removes a probe from the instruction at the specified the address. The comparison used is reference equality, not .equals().

Parameters:

p - the probe to remove

addr - the address from which to remove the probe

insertInterruptProbe

public void insertInterruptProbe(Simulator.InterruptProbe p,
                                 int inum)

The insertInterruptProbe() method inserts an interrupt probe on an interrupt. The probe will then be notified when the interrupt is executed, masked, or posted.

Parameters:

p - the interrupt probe to insert

inum - the interrupt number to insert the probe on

removeInterruptProbe

public void removeInterruptProbe(Simulator.InterruptProbe p,
                                 int inum)

The removeInterruptProbe() method removes an interrupt probe from an interrupt. The probe will then no longer be notified when the interrupt is executed, masked, or posted.

Parameters:

p - the interrupt probe to remove

inum - the interrupt number to remove the probe from

insertWatch

public void insertWatch(Simulator.Watch p,
                        int data_addr)

The insertWatch() method allows a watch to be inserted at a memory location. The probe will be executed before every read or write to that memory location.

Parameters:

p - the probe to insert

data_addr - the data address at which to insert the probe

removeWatch

public void removeWatch(Simulator.Watch p,
                        int data_addr)

The removeWatch() method removes a given watch from the memory location. Reference equality is used to check for equality when removing probes, not .equals().

Parameters:

p - the probe to remove

data_addr - the data address from which to remove the probe

insertIORWatch

public void insertIORWatch(Simulator.IORWatch p,
                           int ioreg_num)

The insertIORWatch() method allows an IO register watch to be inserted on an IO register. The watch will be executed before every read or write to that IO register by the program.

Parameters:

p - the probe to insert

ioreg_num - the number of the IO register to insert the watch for

removeIORWatch

public void removeIORWatch(Simulator.IORWatch p,
                           int ioreg_num)

The removeIORWatch() removes an IO register watch from the given register. Reference equality is used to check for equality when removing probes, not .equals().

Parameters:

p - the probe to insert

ioreg_num - the number of the IO register to insert the watch for

forceInterrupt

public void forceInterrupt(int num)

The forceInterrupt() method forces the simulator to post the specified interrupt regardless of the normal source of the interrupt. If there is a flag register associated with the specified interrupt, then the flag register's value will be set as if the original source of the interrupt (e.g. a timer) had posted the interrupt. As with a normal post of the interrupt, if the interrupt is masked out via a mask register or the master interrupt enable bit, the interrupt will not be delivered. The main reason that this interface exists is for forcing programs to handle interrupts and observe their behavior.

Parameters:

num - the interrupt number to force

insertEvent

public void insertEvent(Simulator.Event e,
                        long cycles)

The insertEvent() method inserts an event into the event queue of the simulator with the specified delay in clock cycles. The event will then be executed at the future time specified

Parameters:

e - the event to be inserted

cycles - the number of cycles in the future at which to fire

insertTimeout

public void insertTimeout(long cycles)

The insertTimeout() method inserts an event into the event queue of the simulator that causes it to stop execution and throw a Simulator.TimeoutException when the specified number of clock cycles have expired.

Parameters:

cycles - the number of cycles to run before timing out

removeEvent

public void removeEvent(Simulator.Event e)

The removeEvent() method removes an event from the event queue of the simulator. The comparison used is reference equality, not .equals().

Parameters:

e - the event to remove

insertExceptionWatch

public void insertExceptionWatch(Simulator.ExceptionWatch watch)

The insertExceptionWatch() method registers an ExceptionWatch instance.

Parameters:

watch - The ExceptionWatch instance.

delay

public void delay(long cycles)

The delay() method introduces a delay in the execution of the instructions of the program. This is used by some devices for correct timing behavior. For example, the EEPROM, when written, causes a small delay in which no instructions are executed.

Parameters:

cycles - the number of cycles to delay the simulation