Upload
dinhkhue
View
214
Download
0
Embed Size (px)
Citation preview
Comp145 UNC Chapel HillImplementation Manual
GUI Computer SimulatorTeam #8
Client: Dr. Frederick P. Brooks Jr.and Prof. Greg Welch
May 1, 2001
Chris Bailey [Admin]_______________________
Ed Goode [Librarian]_______________________
Andy Hans [Q&A]_________________________
Cary Hall [Director]________________________
John Ehrhardt [Producer]___________________
Changes
4-29-01
– Introduction altered.
– Control Model completely redone
– 3.1 minor changes.
– Traceability altered
– Data Flow diagram altered.
Preface
This Implementation manual is an internal document that addresses the
technical aspects of implementing the Computer Simulator. It will cover the
architecture choices, selection of APL interpreters, and data models for the user
programs and machine definitions. This is a low-level analysis, and may require
an implicit understanding of the technologies used.
1 Introduction
The computer simulator project was entirely new. There was no pre-
existing simulator to either mimic or alter. There is a semi-formal syntax for
machine definitions used in Professor Frederick Brooks’ textbook, and the
product must utilize that syntax in parsing machine definitions to determine the
listing of memory and register spaces in the emulated machine.
No prototypes existed at the outset of the project. Users must be able to
run the product on a Windows PC, but this can be achieved via running the JVM
on a Linux/Unix host and exporting the display via use of an X-Server on the
Windows PC, or via a Socket connection from a Windows JVM to the APL
interpreter.
2 High-Level Design Specification
Users interact with the product via a GUI interface and importing machine
definitions and program code.
Structural ModelThis model illustrates the internal structure of the application and the
interactions between the java objects and APL Interpreter.
3 Detailed Design Specification3.1 Object Model
The following sections contain only descriptions of the classes. It does not
provide a deep description containing function and variable lists and descriptions.
For this information, please refer to the source code library.
A. GUIThis class contains links to all componets of the gui. This class
also serves as the window listener for the various subclasses of Frame.
A.1 Control WindowThis class is the main program window where the user chooses
which architecture to run as well as loading and saving state,
closing the program, creating a memory window, and creating a
register window. This frame shows the log of the program, which
notifies the user of any errors and previous commands.
A.2 Memory Window(s)Class MemWindow shows a representation of the memory
contents of a machine. The values and addresses can be shown in
the representation that the user specifies, granted that the
representation wanted fits some parameters from the default base
of the machine.
In order to build a memory window the user must input a
base address and an end address and also the representation that
they are entering those addresses in. Once this data is processed
to obtain the size of memory that they want to view, the user is
prompted for the base in which they want addresses displayed and
also the data representation that they wish to see.
A memory window is then created and shown with the
inputted parameters. A menu item on the menuBar can change the
parameters of this window. Actually the window is not changed, it
is destroyed and removed from the program and a new window is
created and displayed. This makes the harsh job of reformatting
the window unnecessary!
A.4 Register Window(s)This class shows the contents and values of the registers for
a particular machine. Once an architecture is chosen, the names
and default values of the registers are sent to the constructor and
the Frame is built and displayed. The values in the window can be
viewed in the different formats as in all other windows (bin,hex,oct).
This window can be hidden/shown by the control window under the
Window menu.
B. GUI ActionThis class serves as the actionListener and handler for class GUI.
All actions that occur are sent here and are handled accordingly.
References to all components of GUI are passed into the initialize
function. The constructor is default because it is not yet ready to be
constructed at the time that needs to be declared.
C. APL Interpreter ( Controlled through sockets )The actual machine emulation runs in the APL interpreter.
Unfortunately, in the current version, there are no working APL machine
definitions. In contrast to not having a machine definition, everything else
is in place and only one simple execution method must be written for the
interface to work with the definition.
Luckily, one does not need to be an APL master in order to get this
application up and running. One only needs two workspaces to simulate a
computer: SimStart and the computer definition workspace. A working
computer definition has not been found, but only needs minor
modification. On the other hand, SimStart has already been defined and
needs no modification. SimStart is a relatively simple workspace. It
includes the Soliton SharpAPL Java Interface subroutines as well as some
methods used to interact with the simulated machine. These are:
start – This method is called after loaded both workspaces into the
interpreter to spawn the GUI. It looks rather complicated, but all it does is
set indexing to start at 0 (if not already,) set up the SJI connectivity to the
JVM, and instantiate the GUI. This method takes two parameters: the
host name and the host port. (Example: ‘atlanta.cs.unc.edu’ start 1091)
readVar – This method is called to give the GUI the value of a
variable. It actually executes APL code. Only the name of the variable
needs to be passed to subroutine, otherwise one might start executing
other APL code that can crash the interpreter and disconnect the SJI. By
default the SJI passes a numerical reference to the process that called the
function. (Example: 100003 readVars ‘acc’)
loadVar – This method is called to set the values of variables in the
interpreter. There are problems with this function in the current version on
the simulator when a large numerical value is assigned. A float may be
assigned to the variable when something else is expected. This
subroutine acts similar to readVar but it takes in a vector containing the
variable name and value as well as the source id. (Example: 100003
loadVars (‘acc’,12345678901))
fetchMem – This method returns a matrix with each column being
one bit or whatever radix digit the machine is set in and each row being
one word for a specified memory range. Two parameters are passed to
this subroutine: the starting memory address and the ending memory
address. This subroutine unfortunately does not check to make sure that
the range is within the machine’s memory capacity, so be sure not to
overstep the bounds of the machine, otherwise the interpreter will crash.
(Example: 1000003 fetchMem (1000,1200))
loadMem – This method sets one word in memory. Again there is
no index out of bounds checking in memory, so be careful. The
parameters to the subroutine are similar to the rest of the functions. Of
course the source process id will be sent, but the other parameter is a little
more complicated. The second parameter is a vector with the first value
being the position in memory that is to be set. The rest of the vector is the
word itself. Therefore make sure that it is in the proper radix!!! I do not
want to know what happens when I binary machine is passed a decimal
digit. (Example: 100003 loadMem (201,0,1,0,0,0,1,1,0))
D. APL CallbacksThis class is the set of methods that will be driven by user events that
need to make calls to the APL interpreter. SharpAPL Java Interface (SJI
hereafter) provides an object kernel.SJListener for making synchronous calls
to the interpreter, through SJListener.invoke(), and asynchronous threaded
calls through SJListener.runMethod(methodname).
The methods in this class are one of two types. Some are public void with
no arguments. These are of the sort that may be called via
SJListener.runMethod(), since it may pass no arguments, and has no return
type. Others either have arguments, and these are intended to set the
parameters for the void/no arg functions that will call the APL interpreter. The
calling location MUST use the following synchronization style to avoid having
it's parameters being cleared by another threads call to setArgs.
synchronized(APLCallbacks){
APLCallbacks.setArgs(arg1, arg2....)
SJListener.runMethod(APLCallbackMethodName)
}
You MUST call .initialize after constructing an APLCallbacks object, or it
will not function. In fact, initialize returns the SJListener necessary to invoke
asynchronous methods on the APLCallbacks object.
The methods in this class are not extremely important for updating this
application. Changes in the interpreter do not affect APL Callbacks as long
as the set and fetch functions contained in the SimStart workspace are left
alone. Also, the GUI can be modified and still utilize these same methods. If
one wants to analyze the code, it is fully documented and located in the
source library.
E. State ParserThis class is designed to implement file parsing/reading from
machine state files that have been defined by our group. It uses standard
buffered file input to read memory states for any particular architecture
currently loaded in the machine emulator by a user.
File parsing is mainly controlled by the function parse() which sends
off requests to parse memory values or register states depending on what
is currently being read from the file. For information on how this type of file
is formatted, see one of the sample state text files included with this code.
These methods are used to load machine states, are fully
documented and can be further explored in the source library.
F. Save State to FileThis static class is used as a toolbox for saving state and the log to
a file. At any call to save the state from GuiAction a call to saveToFile is
made with the parameters that need to be saved. For instance if only the
log is to be saved, a reference to the control window is passed in all other
parameters, except for the reference to the TextArea (a reference to the
program log)and a file name is passed in as null. These parameters are
examined and by anything that is sent in are saved to the file name that is
passed in.
This file is written in a machine-readable format that can be
reloaded into memory. The '#' symbol is used a comment delimiting
character.
3.2 Data Flow
3.3 Technology ChoicesWe selected Soliton Associates’ SharpAPL (aka SAX) as our APL
interpreter. The two main reasons for this selection were that it was already
installed on the department machine Atlanta, and it has an extension for
interfacing with a Java Virtual Machine. It also did not hurt that it was free. We
did not locate any other interpreter with a reasonably simple interface to GUI
programming.
We elected to code the GUI in AWT rather than Swing. As a result, the
Simulator will run on a 1.1.x JVM instead of a 1.2.x only. It gives us less control
over the actual look of the GUI, but ultimately it runs faster as it uses the OS’s
native widgets instead of heavy-weight widgets loaded from the JVM.
3.4 Working in APL (running the simulator)APL is a very old and complicated language. No one should ever want to
use it, but because the computer definitions had previously been coded in APL, it
was the logical choice for this project. If one were not familiar with APL, reading
the APL appendix in Dr. Brooks’ computer architecture book as well as another
APL primer in Dr. Brooks’ library would be very helpful.
Luckily, one should not have to write any APL code at all to use this
application. The APL is already present in a workspace (SimStart in library 8)
that contains all of the Java connectivity and the interaction with the machine
definition. Unfortunately, only one subroutine remains to be written once a
usable machine definition is found. This is executeInst. It will execute the next
instruction and then return 1 or 0 depending on whether the end of the program
has been reached or not. Fortunately, Team 8’s APL man is a junior this year
and will be available for help during the 2001-2002 year at
[email protected]. Please feel free to contact him about any question on
what should be done to finish the APL execution.
The APL defined functions are listed in Section 3.1 C. It is suggested that
the functions be viewed/edited using the full screen editor. It is invoked by typing
TAB, e, Function_Name. Also, TAB, q quits, TAB, z, saves and quits, and TAB,
w, Function_Name, saves. Please familiarize yourself with the SharpAPL
Handbook if not the entire manual if one is going to be editing APL code.
To start the application, simply start up sax (with the fonts loaded first,
refer to “howto apl” the unix command), type in “)load 8 SimStart” then on the
next line type “)copy 8 Machine_WorkSpace_Name”, then initialize the machine
with its initialization function. For the IBM650 it is initiate650. After that has been
done, execute the start function (Example: ‘atlanta.cs.unc.edu’ start 2031.) The
JVM must have been started prior to calling the start function using the startjava
script.
Please refer to Dr. Brook’s book on computer architecture for the structure
and meaning of the APL machine definitions.
3.5 Further Implementation NotesSince the project was not completed, there are some things left to
accomplish.
Chief among these is to provide a working machine definition, which is
beyond our scope of knowledge. Along with a working machine definition, APL
functions for loading and fetching register and memory states, and an APL
function for executing a single machine instruction are also required. We have
working versions of load and fetch routines. The set-register routine occasionally
assigns the register as a float in the interpreter instead of as a character vector.
We’re not sure why this is happening, and currently only small (<6 element)
registers are being set properly. As far as we know, the only changes on the
Java side that need to be made lie in APLCallbacks, which must change to
accommodate whatever interface is designed between APL Interpreter and Java
Engine.
4 Maintenance Procedures and IssuesBecause this application was never totally finished, further maintenance
issues need to be addressed besides simple descriptions provided in section 3.1.
There are two subsections to this chapter, one addressing maintaining the Java
source code, and another addressing maintaining the APL SJI code and
computer definitions.
4.1 Java Source CodeResides in $SIMULATOR/GUI after installation. There are four main
groupings of Java Classes that compose the Simulator, as represented in the
following diagram by items A, B, D, E, and F of the Structural Model (Section 2,
Implementation Manual).
A. GUI Classes1) Gui – The main starting point of the Java-side of the Simulator
2) MemWindow – Handles the displaying of Memory state
3) ControlWindow – The ‘main’ window, containing menus for user
actions and a log for error messages.
4) RegWindow – Displays register contents
5) MemDialog – Walks the user through parameter input for
new/altered MemWindows.
These classes are primarily presentation logic. There are methods to
set the data of MemWindows and RegWindows, and methods on
ControlWindow to change which buttons/menus are active, but other
than that they are only for presentation of GUI.
B. Event Broker ClassGuiAction is the class containing all the logic for matching events to
function calls, with the exception of WindowEvents, which go to Gui
(see above). GuiAction is primarily responsible for connecting the GUI
classes of A to the APL Callbacks module (C). Because of the sheer
number of ActionEvents in the system, GuiAction is substantially large
class. It will require an instance of kernel.SJListener (from the SJI jar
files) in order to run threaded function calls on APLCallbacks.
Because of the role that GuiAction plays, it requires a reference to
nearly every component of the system (on the Java-side, that is).
GuiAction also required a reference to an SJListener, which is created
by APLCallbacks, which required a reference to GuiAction. This cyclic
dependency makes for an interesting initialization phase in Gui.
C. APL Callbacks ModuleAPLCallbacks is the class responsible for ALL dealings with the
APL interpreter. Any call to APLCallbacks that results in interaction
with the interpreter must be threaded and have no return or
parameters. Thus, it takes two function calls, one to set parameters
and one to call the void/no-args function. APLCallbacks also requires
references to most of the components of the GUI, since it will be
responsible for updating their contents after each machine instruction
execution.
4.2 APL WorkSpacesThere are only two required workspaces for the computer simulator:
SimStart and the computer definition.
A. SimStartSimStart is the workspace containing all of the SJI connectivity to
the Java Virtual Machine as well as the subroutines for reading/writing
into the simulated computer’s state. To find more information about
SJI, visit Soliton’s SJI website, which is found at
(http://www.soliton.com/Interfaces/Java_Interface/java_interface.html.) Also
please refer to the SAX/SharpAPL manual – Handbook section for help
on the APL programming environment. Please refer to section 3.4 and
3.1.C for more information about the implementation of SimStart.
B. Computer DefinitionThe unprovided computer definitions are all that are required for the
final implementation of this project. These definitions should be
provided by Dr. Brooks, but if they are not, their structure and some
functionality is defined in his book, Computer Architecture: Concepts
and Evolution.
Currently, there are a few computer definitions that were
unexpectedly received from Gerrit A. Blaauw one week before the end
of the semester. Unfortunately the team was unable to identify which
APL interpreter was used to write the definitions. We suspect that
APL*PLUS was used, but it is no longer in production or supported.
Hopefully its descendant, APL2000 will load these workspaces. It is
suggested that the definitions be written out to a file to be imported into
SharpAPL or simple cut and paste methods be used to get a working
definition. Once that has been accomplished, only coding the execute
instruction subroutine based on the machine’s cycle method needs to
be coded.
5 Requirements TraceabilitySee Appendix A
6 Schedule
Given the amount of problem and delays we experienced, we were not
obliged to follow our original schedule. Basically, we just pounded forward as
quickly as possible once we got interaction between SAX and Java. Because of
the delays in getting a working interpreter and machine definitions, we were far
behind schedule, but the tasks were partitioned well enough that everyone had
only one area to work within, with one exception. Because of this, the only
deadline was the end of the semester. After a huge amount of work in the last