NeXTspim

I developed NeXTspim under NeXTstep 2.1 on black hardware.  I do not know whether or not it will compile on other platforms or with a newer verison of the OS.  

Changes to existing code:
The function write-output no longer has the first int argument to specify the window.  All output will go to the Messages window.   mips-syscall.c and mem.c were changed to reflect this.

A line was commented out in mem.c to prevent the memory-mapped I/O routines from doubling the characters on the screen.  Since NeXTspim uses a ConsoleText object, the characters are automatically placed.

The initialize_world function in spim-util.c has been modified to include the path of the executable in the filename for the default trap handler.  This is important, since the working directory of an executable launched from the File Viewer is the user's home directory, not the directory where the executable is.

New NeXT-specific Code:
xpsim.c and button.c have been replaced by:
SPIMInterface.[hm]	Main window, display registers, etc...
BreakpointsPanel.[hm]	Set/Clear Breakpoints
ContinuePanel.[hm]	Pops up when breakpoint encountered
KeyQueue.[hm]		Save keyboard input until needed.
PrefsPanel.[hm]		Change the preferences (Note: Command line prefs are not supported)
RunLoop.[hm]		Code for simulation thread (see below)
SetValuePanel.[hm]	Set a register value
StatsWindow.[hm]	A window class for displaying statistical information when it is called up

The *Panel classes are descendants of Panel.  Instead of creating a Panel with the controls and an Object descendant to handle the panel, one object performs both functions.  The controls in each of these windows are connected to the button: or switch: method of the new class.

In addition, the following new views were created to make certain tasks easier:
TextView:ScrollView	A scroll view that creates its own Text object, with functions for easily adding text.  Vertical scroller only.  Uses the "Courier" font.  Used for viewing registers and data.
CodeView:TextView	Adds a horizontal scroller.  Used for viewing code, since I want to keep all code for one address on the same line.
ConsoleView:TextView	Creates a ConsoleText object instead of a Text object and allocates a KeyQueue for it.

A Text subclass was also created:
ConsoleText:Text	Overrides default keyDown: procedure to ignore arrow keys and control characters and to put characters into a specified KeyQueue.

Threads
The original xspim code used only a single program thread, but my new interface makes this harder to do, and I was having a hard time understanding the execution code.  To make things simpler, NeXTspim runs two threads, an interface thread (the orginal thread) and the simulation thread (contained entirely in RunLoop.[hm]).  Responsibilities of each:

Interface thread:
	Most user input (via buttons, ConsoleText, etc.)
	All output
	Starting/Stopping the simulation
	Setting options and starting values.
	
Simulation thread:
	Calling simulation code.
	Calls input/output functions, but should not directly output to console or any NeXTstep object  (The exception is the keyboard input syscall.  The simulation thread does directly call the KeyQueue object, but it should not receive the keyDown message.  Console output, however, is buffered and handled by the interface thread.)

The function UpdateDisplayIfNeeded (in SPIMInterface.m) is called by the interface thread at user-definable intervals, using the DPSAddTimedEntry function.  This function changes the highlighting, outputs text to the Messages window, opens the Continue window, redisplays the registers, and should be responsible for anything the simulation thread needs to do.  The simulation thread does not call this function directly but sets flags to order it to perform actions.  InitUpdateDisplayLoop and KillUpdateDisplayLoop are used to start and stop the timed updates.  

Mutexes:

RunMutex	Permission to start or stop the simulation
DisplayMutex	Permission to change the display update flags
RegisterMutex	Permission to change the registers

(In addition, KeyQueue contains an internal mutex variable to ensure that its contents remain unchanged when it is being read from.)

SPIM files:
data.[ch]	Code to handle data directives.
inst.[ch]	Code to build instructions and manipulate symbol table.
mem.[ch]	Code to maintain memory.
mips-syscall.[ch]	Code to handle system calls and exceptions.
op.h	Definition of operations.
parser.[yh]	Assembly command parser (YACC).
read-aout.[ch]	Code to read MIPS a.out executables.
reg.h	Register access macros.
run.[ch]	Instruction simulator.
scanner.[lh]	Lexical analyzer (LEX).
spim-syscall.h	System call numbers.
spim-utils.[ch]	Misc. routines.
sym-tbl.[ch]	Symbol table.
trap.handler	Standard trap handler.
Documentation/spim.ps	Postscript document that describes SPIM.
Documentation/cycle.ps	Describes Anne Roger's cycle-level simulator (cl-spim, cl-xspim).
cl-cycle.[ch]	Pipeline simulation
cl-except.[ch]	Exception and signal handling
cl-tlb.[ch]	Virtual memory simulation
cl-cache.[ch]	Instruction and data caching simulation

Unimplemented Features

Memory-mapped I/O
It sort of works; at least no errors occur.  However, the test program doesn't work correctly as far as I can tell (although I'm not sure what it's supposed to do).  The code is all there, but the old memory-mapped I/O functions don't seem to be getting along with the NeXTspim code.  If someone could actually decide whether it works or not, I'd be eternally grateful.

Reading MIPS Binary Files
The code exists, but no user interface has been created, and the file loading functions do not detect the type of the file automatically.

Bugs
When the program is waiting for keyboard input, there is no indication given; it looks as if the program is running but doing nothing.  If the user tries to stop the program it will keep running, since (1) it is waiting for a full line and (2) instructions are executed 100 at a time.  The second is easily adjustable, the first is a bit harder.

Surprising Features
The user can type into the Message window before input is asked for.  Since the KeyQueue object will hold those characters, the next time the program asks for input it will already be there.  However, the KeyQueue buffer is cleared when the program is run, so there shouldn't be too many unexpected things happening.

Wish List
1. Allow MIPS programs to call UNIX syscalls from within NeXTspim.  This will allow programs to do file I/O and write in "real" code, instead of relying on the pseudo-operating system provided by the NeXTspim syscalls.  It will also give a better idea of how much time 

2. Better statistics information.  At the very minimum, a count of how many cycles a given program takes to execute, and perhaps a summary of the number of times each line was executed.

Feel free to E-mail your comments, complaints, or additions to the "wish list".  I am very interested in finding out where NeXTspim is being used and what you think of it.

Mark Gritter
mgritter@gac.edu
April 23, 1994