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.

Control ModelThis Model shows how the user can interact with the application.

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

johnehr@email.unc.edu. 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

month, in the end we actually finished our end of the contract without a working

APL definition. Since everything is set up for interaction with the emulated

machines on time, one could conceivably say that we finished our project on

time.