edsim51sh
Class TargetBoard

java.lang.Object
  extended by 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
TargetBoard()
           
 
Method Summary
 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.
int getBatchElapsedTime()
          This method returns the length of time (in microseconds) the current batch of 8051 instructions has been executing.
int getInstructionElapsedTime()
          This method returns the length of time (in microseconds) the most recent 8051 instruction took to execute.
long getProgramElapsedTime()
          This method returns the length of time (in microseconds) the current 8051 program has been executing.
 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.
 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.
 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 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.
abstract  void writeToPortPins(PortLatches portLatches)
          The programmer must provide an implementation of this abstract method.

Constructor Detail

TargetBoard

public TargetBoard()
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:
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 *.*.*

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

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 left 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 left 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)
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. 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)
Clear a port pin (ie: to logic 0), given the port number and the pin number.
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.

writeToPortPins

public abstract void writeToPortPins(PortLatches portLatches)
The programmer must provide an implementation of this abstract method. This method is called by the simulator 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 write to the port pins (using the setPortPin() and clearPortPin() methods in this class) in accordance with the target board implementation.
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.

Parameters:
portLatches - A copy of the port latches is provided to this method for the target board programmer's convenience. However, it is not necessary for the programmer to examine the latches. 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() method does the checking and fails to set the pin if the latch is 0. Remember, a pin can never be 1 if its latch is 0.

getInstructionElapsedTime

public int getInstructionElapsedTime()

        This method returns the length of time (in microseconds) the most recent 8051 instruction took to execute, according to the 8051 running with system clock of         12 MHz. For example, a 2-cyle instruction would take 2 microseconds as each cycle is one microsecond.

        Returns:
            Instruction elapsed time in microseconds.

getBatchElapsedTime

public int getBatchElapsedTime()

        This method returns the length of time (in microseconds) the current batch of 8051 instructions has been executing, according to the 8051 running with system
        clock of 12 MHz.
        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:
            Batch elapsed time in microseconds.

getProgramElapsedTime

public long getProgramElapsedTime()

        This method returns the length of time (in microseconds) the current 8051 program has been executing, according to the 8051 running with system clock of 12         MHz.
        The program elapsed time is updated after each 8051 instruction execution.

        Returns:
            Program elapsed time in microseconds.

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).
When the simulator's GUI is 'small' the space provided for the target board is 1024 pixels wide by 210 high (therefore, when it's 'large' the space is 1024 * 1.5 = 1536 by 210 * 1.5 = 315). However, the target board is not restricted to this size as its JPanel gui is placed in a scroll window - if the board is bigger than the space provided it will be scrollable.

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