edsim51sh

Class TargetBoard

java.lang.Object

edsim51sh.TargetBoard

public abstract class TargetBoard
extends java.lang.Object

This abstract class contains concrete methods for setting and clearing port pins and for connecting the target board to the simulator. There are also two abstract methods for writing to the port pins and for updating the target board graphics.

Constructor Summary

Constructors

Constructor and Description
TargetBoard() If this constructor is used, the target board's hardware settings will be saved in a file named edsim51shSettings.ser.
TargetBoard(java.lang.String hardwareSettingsFileName) This constructor allows the programmer to name the target board's hardware settings file.

Method Summary

Methods

Modifier and Type	Method and Description
void	clearPortPin(int portNumber, int pinNumber) Clear a port pin (ie: to logic 0), given the port number and the pin number. A call to this method is always successful.
void	clearPortPin(int portNumber, int pinNumber, int hardwareId) Clear a port pin (ie: to logic 0), given the port number and the pin number. THIS FUNCTION MUST BE USED IF MORE THAN ONE PERIPHERAL IS CONNECTED TO THE PORT PIN. A call to this method is always successful.
int	getBatchElapsedTime() This method returns the length of time (in microseconds) the current batch of 8051 instructions has been executing, as determined by the 8051 system clock. A batch size is determined by the Update Frequency menu at the top of the simulator GUI. The batch elapsed time is updated after each 8051 instruction execution.
double	getCpuMachineCycleLength() This method returns the length, in microseconds, of the 8051 machine cycle.
java.lang.String	getHardwareSetting(java.lang.String id) This method returns a target board setting from file.
int	getInstructionCycles() This method returns the most recent 8051 instruction's number of cycles.
int	getInstructionElapsedTime() This method returns the length of time (in microseconds) the most recent 8051 instruction took to execute, as determined by the 8051 system clock.
long	getInstructionElapsedTimeInNanos() This method returns the length of time (in nanoseconds) the most recent 8051 instruction took to execute, as determined by the 8051 system clock.
long	getProgramElapsedTime() This method returns the length of time (in microseconds) the current 8051 program has been executing, as determined by the 8051 running with system clock. The program elapsed time is updated after each 8051 instruction execution.
void	init(javax.swing.JPanel gui, java.lang.String title, java.lang.String version) An instance of TargetBoard should contain a JPanel containing the target board's graphics, its title and its version number.
int	readPortLatch(int portNumber, int pinNumber) Read a port latch, given the port number and the pin number. This allows the target board programmer to examine the state of any given latch at any time. Note: this method reads the port latch, not the port pin.
int	readPortPin(int portNumber, int pinNumber) Returns the state of a port pin (1 or 0), given the port number and the pin number.
void	reset() This method does nothing.
void	setHardwareSetting(java.lang.String id, java.lang.String setting) This method saves a target board setting in a file.
boolean	setPortPin(int portNumber, int pinNumber) Set a port pin (ie: to logic 1), given the port number and the pin number. Returns true if the port pin was set, false if not. Note: There is no guarantee that calling this method for a given port pin will result in the pin being set.
boolean	setPortPin(int portNumber, int pinNumber, int hardwareId) Set a port pin (ie: to logic 1), given the port number and the pin number. THIS FUNCTION MUST BE USED IF MORE THAN ONE PERIPHERAL IS CONNECTED TO THE PORT PIN. Returns true if the port pin was set, false if not. Note: There is no guarantee that calling this method for a given port pin will result in the pin being set.
void	setPortPinDescription(int portNumber, int pinNumber, java.lang.String description) This method takes a port number and a pin number together with a String containing the port pin's description.
void	setPortPinDescription(int portNumber, int pinNumber, java.lang.String description, java.lang.String toolTip) This method takes a port number and a pin number together with a String containing the port pin's description and another String containing the pin's tooltip.
abstract void	setTargetBoardGraphicsSize(boolean small) This method is called in response to the zoom button in the simulator's GUI being clicked. With the simulator's default size (ie: small), it may be difficult to see on high resolution monitors.
abstract void	updatePortPins() The programmer must provide an implementation of this abstract method.
abstract void	updateTargetBoardGraphics() This method is called by the simulator after each batch of 8051 instructions has been executed. When the user steps through 8051 code, this method is called after each instruction has been executed.

Methods inherited from class java.lang.Object

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

Constructor Detail

TargetBoard

public TargetBoard()

If this constructor is used, the target board's hardware settings will be saved in a file named edsim51shSettings.ser.

TargetBoard

public TargetBoard(java.lang.String hardwareSettingsFileName)

This constructor allows the programmer to name the target board's hardware settings file. This is advisable because it means separate instances of EdSim51SH with different target boards can have separate hardware settings files.

Parameters:

hardwareSettingsFileName - The hardware settings file name.

Method Detail

init

public void init(javax.swing.JPanel gui,
        java.lang.String title,
        java.lang.String version)

An instance of TargetBoard should contain a JPanel containing the target board's graphics, its title and its version number.

Parameters:

gui - The target board's graphical user interface. This GUI will be placed in the simulator's target board panel.

title - The title pane at the top of the simulator's GUI displays EdSim51SH version *.*.*
If a target board is connected to the GUI, the text in the String title is appended to the simulator's title and version number.

version - The target board's version number is appended to the title in the simulator's GUI.
The finished title will be of the form:
EdSim51SH version *.*.* with Target Board ----- version *.*.*

getCpuMachineCycleLength

public double getCpuMachineCycleLength()

This method returns the length, in microseconds, of the 8051 machine cycle.

Returns:

length of the 8051 machine cycle

setPortPinDescription

public void setPortPinDescription(int portNumber,
                         int pinNumber,
                         java.lang.String description)

This method takes a port number and a pin number together with a String containing the port pin's description. The description is then attached to this pin.

Parameters:

portNumber - A number between 0 and 3, corresponding to P0, P1, P2 and P3 on the 8051. The value in portNumber is ANDed with 3 (11 in binary) to force it to a value between 0 and 3.

pinNumber - A number between 0 and 7, corresponding to the pin numbers of a given port. The value in pinNumber is ANDed with 7 (111 in binary) to force it to a value between 0 and 7.

description - A description of the peripheral this pin is connected to. The first 32 characters in the description will be displayed in the simulator's top right panel. If the description is more than 32 characters long it is truncated to 32 characters.

setPortPinDescription

public void setPortPinDescription(int portNumber,
                         int pinNumber,
                         java.lang.String description,
                         java.lang.String toolTip)

This method takes a port number and a pin number together with a String containing the port pin's description and another String containing the pin's tooltip. The description and tooltip are then attached to this pin.

Parameters:

portNumber - A number between 0 and 3, corresponding to P0, P1, P2 and P3 on the 8051. The value in portNumber is ANDed with 3 (11 in binary) to force it to a value between 0 and 3.

pinNumber - A number between 0 and 7, corresponding to the pin numbers of a given port. The value in pinNumber is ANDed with 7 (111 in binary) to force it to a value between 0 and 7.

description - A description of the peripheral this pin is connected to. The first 32 characters in the description will be displayed in the simulator's top right panel. If the description is more than 32 characters long it is truncated to 32 characters.

toolTip - A tooltip for the pin can also be set. The tooltip text will then appear when the user lets the mouse pointer hover over the pin's description. Setting the tooltip is optional. If the target board programmer would rather not set the tooltip, the other version of setPortPinDescription() should be used (see above).

setPortPin

public boolean setPortPin(int portNumber,
                 int pinNumber,
                 int hardwareId)

Set a port pin (ie: to logic 1), given the port number and the pin number.
When setting a port pin, THIS METHOD MUST BE USED IF MORE THAN ONE PERIPHERAL IS CONNECTED TO THE PORT PIN.
Returns true if the port pin was set, false if not.
Note: There is no guarantee that calling this method for a given port pin will result in the pin being set. If the corresponding latch is at logic 0 then the pin will not be set.
This method should be used by the writeToPortPins() method in this class, to handle updating of the port pins after each instruction execution. But it may also be called to handle asynchronous events, such as the user opening or closing a switch on the target board.

Parameters:

portNumber - A number between 0 and 3, corresponding to P0, P1, P2 and P3 on the 8051. The value in portNumber is ANDed with 3 (11 in binary) to force it to a value between 0 and 3.

pinNumber - A number between 0 and 7, corresponding to the pin numbers of a given port. The value in pinNumber is ANDed with 7 (111 in binary) to force it to a value between 0 and 7.

hardwareId - The hardware ID is required if more than one peripheral is connected to the port pin. The system needs to keep track of which piece of hardware is holding the port pin low. Each peripheral connected to an individual port pin must have a unique id - any integer greater than zero.

Returns:

true if setting the port pin was successful

setPortPin

public boolean setPortPin(int portNumber,
                 int pinNumber)

Set a port pin (ie: to logic 1), given the port number and the pin number.
This method can be used when setting a port pin IF THERE IS ONLY ONE PERIPHERAL CONNECTED TO THE PORT PIN.
Returns true if the port pin was set, false if not.
Note: There is no guarantee that calling this method for a given port pin will result in the pin being set. If the corresponding latch is at logic 0 then the pin will not be set.
This method should be used by the writeToPortPins() method in this class, to handle updating of the port pins after each instruction execution. But it may also be called to handle asynchronous events, such as the user opening or closing a switch on the target board.

Parameters:

portNumber - A number between 0 and 3, corresponding to P0, P1, P2 and P3 on the 8051. The value in portNumber is ANDed with 3 (11 in binary) to force it to a value between 0 and 3.

pinNumber - A number between 0 and 7, corresponding to the pin numbers of a given port. The value in pinNumber is ANDed with 7 (111 in binary) to force it to a value between 0 and 7.

Returns:

true if setting the port pin was successful

clearPortPin

public void clearPortPin(int portNumber,
                int pinNumber,
                int hardwareId)

Clear a port pin (ie: to logic 0), given the port number and the pin number.
When clearing a port pin, THIS FUNCTION MUST BE USED IF MORE THAN ONE PERIPHERAL IS CONNECTED TO THE PORT PIN.
A call to this method is always successful. It doesn't matter what is the state of the corresponding latch, pulling a port pin to ground always works.
This method should be used by the writeToPortPins() method in this class, to handle updating of the port pins after each instruction execution. But it may also be called to handle asynchronous events, such as the user opening or closing a switch on the target board.

Parameters:

portNumber - A number between 0 and 3, corresponding to P0, P1, P2 and P3 on the 8051. The value in portNumber is ANDed with 3 (11 in binary) to force it to a value between 0 and 3.

pinNumber - A number between 0 and 7, corresponding to the pin numbers of a given port. The value in pinNumber is ANDed with 7 (111 in binary) to force it to a value between 0 and 7.

hardwareId - The hardware ID is required if more than one peripheral is connected to the port pin. The system needs to keep track of which piece of hardware is holding the port pin low. Each peripheral connected to an individual port pin must have a unique id - any integer greater than zero.

clearPortPin

public void clearPortPin(int portNumber,
                int pinNumber)

Clear a port pin (ie: to logic 0), given the port number and the pin number.
This method can be used when clearing a port pin IF THERE IS ONLY ONE PERIPHERAL CONNECTED TO THE PORT PIN.
A call to this method is always successful. It doesn't matter what is the state of the corresponding latch, pulling a port pin to ground always works.
This method should be used by the writeToPortPins() method in this class, to handle updating of the port pins after each instruction execution. But it may also be called to handle asynchronous events, such as the user opening or closing a switch on the target board.

Parameters:

portNumber - A number between 0 and 3, corresponding to P0, P1, P2 and P3 on the 8051. The value in portNumber is ANDed with 3 (11 in binary) to force it to a value between 0 and 3.

pinNumber - A number between 0 and 7, corresponding to the pin numbers of a given port. The value in pinNumber is ANDed with 7 (111 in binary) to force it to a value between 0 and 7.

readPortPin

public int readPortPin(int portNumber,
              int pinNumber)

Returns the state of a port pin (1 or 0), given the port number and the pin number.

Parameters:

portNumber - A number between 0 and 3, corresponding to P0, P1, P2 and P3 on the 8051. The value in portNumber is ANDed with 3 (11 in binary) to force it to a value between 0 and 3.

pinNumber - A number between 0 and 7, corresponding to the pin numbers of a given port. The value in pinNumber is ANDed with 7 (111 in binary) to force it to a value between 0 and 7.

readPortLatch

public int readPortLatch(int portNumber,
                int pinNumber)

Returns the state of a port latch (1 or 0), given the port number and the pin number.
This allows the target board programmer to examine the state of any given latch at any time.
Note: this method reads the port latch, not the port pin.

Parameters:

portNumber - A number between 0 and 3, corresponding to P0, P1, P2 and P3 on the 8051. The value in portNumber is ANDed with 3 (11 in binary) to force it to a value between 0 and 3.

pinNumber - A number between 0 and 7, corresponding to the pin numbers of a given port. The value in pinNumber is ANDed with 7 (111 in binary) to force it to a value between 0 and 7.

Returns:

1 if the latch is set, 0 if it is clear

getInstructionCycles

public int getInstructionCycles()

Returns the number of cycles of the most recently executed 8051 instruction.

Returns:

number of cycles for the most recent instruction

getInstructionElapsedTime

public int getInstructionElapsedTime()

Returns the length of time (in microseconds) the most recent 8051 instruction took to execute, as determined by the 8051 system clock.

Returns:

the length of time for the most recent instruction

getInstructionElapsedTimeInNanos

public long getInstructionElapsedTimeInNanos()

Returns the length of time (in nanoseconds) the most recent 8051 instruction took to execute, as determined by the 8051 system clock.

Returns:

the length of time in nanoseconds for the most recent instruction

getBatchElapsedTime

public int getBatchElapsedTime()

Returns the length of time (in microseconds) the current batch of 8051 instructions has been executing, as determined by the 8051 system clock.
A batch size is determined by the Update Frequency menu at the top of the simulator GUI.
The batch elapsed time is updated after each 8051 instruction execution.

Returns:

the length of time the current batch has been executing

getProgramElapsedTime

public long getProgramElapsedTime()

Returns the length of time (in microseconds) the current 8051 program has been executing, as determined by the 8051 running with system clock.
The program elapsed time is updated after each 8051 instruction execution.

Returns:

the length of time the current program has been running

setHardwareSetting

public void setHardwareSetting(java.lang.String id,
                      java.lang.String setting)

Saves a target board setting in a file. The name of the file depends on which constructor was used. See the constructors above for more details.

Parameters:

id - the setting's id. If this id already exists, then its data is overwritten. If it does not exist, it is created.

setting - the setting's data

getHardwareSetting

public java.lang.String getHardwareSetting(java.lang.String id)

Returns a target board setting from file. The name of the file depends on which constructor was used. See the constructors above for more details.

Parameters:

id - the setting's id

Returns:

the setting's data, if id exists, null if id does not exist

reset

public void reset()

This method does nothing. It is called when the GUI's reset button is pressed. Therefore, by default, a target board does not respond to the reset button being pressed. If you want the target board to respond to the reset button being pressed, you should override this method.

updatePortPins

public abstract void updatePortPins()

The programmer must provide an implementation of this abstract method. This method is called during each 8051 instruction execution.
The simulator first sets all port pins equal to their corresponding latches.
It is up to the programmer developing a target board implementation to update the port pins (using the setPortPin() and clearPortPin() methods in this class) in accordance with the target board implementation.
If a pin is to be cleared by the target board, then it will succeed, regardless of the state of the latch. If a pin is to be set, then the target board can attempt to set the pin, without checking the latch. The setPortPin() methods do the checking and fail to set the pin if the latch is 0. Remember, a pin can never be 1 if its latch is 0.
Note: no updating of the target board's graphics should be carried out by this method. Many instructions may be executed between updates to the simulator GUI. Therefore, updating the target board's graphics should be left to the updateTargetBoardGraphics() method.

updateTargetBoardGraphics

public abstract void updateTargetBoardGraphics()

This method is called by the simulator after each batch of 8051 instructions has been executed.
When the user steps through 8051 code, this method is called after each instruction has been executed. However, when the user is running 8051 code, the instruction batch size depends on what the user selected from the Update Freq. menu. If, for example, the user selected 100, then 100 instructions are executed, and then the simulator's GUI is updated. At this time, this method is called to update the target board's graphics. All updating of the target board's graphics (except for asynchronous events, such as a user pressing a button on the target board) should be handled by this method.

setTargetBoardGraphicsSize

public abstract void setTargetBoardGraphicsSize(boolean small)

This method is called in response to the zoom button in the simulator's GUI being clicked.
With the simulator's default size (ie: small), it may be difficult to see on high resolution monitors. Therefore, the zoom button was included. It allows the user to toggle between large and small versions of the GUI. The target board programmer must provide an implementation for this method so that clicking the zoom button will also toggle between large and small versions of the target board GUI.
The scale factor from small to large is 1.5 (ie: the dimensions of each component in the GUI are 1.5 times greater in the large version than in the small version).

Parameters:

small - If true: resize the target board GUI to 'small'
If false: resize the target board GUI to 'large'