Comp145 UNC Chapel Hill

Comp145 UNC Chapel Hill

Implementation Manual

GUI Computer Simulator

Team #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 Model

This model illustrates the internal structure of the application and the interactions between the java objects and APL Interpreter.

Control Model

This Model shows how the user can interact with the application.

3 Detailed Design Specification

3.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. GUI

This 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 Window

This 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 Action

This 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 Callbacks

This 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 Parser

This 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 File

This 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 Choices

We 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 . 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 Notes

Since 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 Issues

Because 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 Code

Resides 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 Classes

1) 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 Class

GuiAction 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 Module

APLCallbacks 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.