.TH rsp 1P local "Silicon Graphics, Inc."
.SH NAME
rsp, rspg, rsp_ops \- Ultra 64 signal processor (RSP) simulator

.SH SYNOPSIS
\f3rsp\f1 [-vs] [script_file]
.br
\f3rspg\f1 [-s] [script_file]
.br
\f3rsp_ops\f1
.SH DESCRIPTION
.I rsp\^
is a simulator and debugger for the Ultra 64's Reality Signal Processor (RSP).
.I rsp
can be run in text-mode (as \f2rsp\f1), in curses mode (as \f2rsp -v\f1), and
with a graphics interface (as \f2rspg\f1).
.I rsp_ops\^
is a utility program which dumps out the RSP opcode syntax.
.PP
Command line options are:
.RS 5
.TP 12
.B \-v
Runs in curses mode.
.TP
.B \-s
Puts spaces every four digits of the vector display in visual or
graphics mode.
.PP
\f2script_file\f1 is an optional simulator script that can be invoked
at start-up.

.SS "\f2Text Mode\f1"
When the simulator is run, it starts up in a command mode. In this
mode, the user can control the RSP. The command set is a combination
of typical assembly-level debugging commands plus some more unusual
ones to help control the RSP.

Execution of the simulator can be stopped by typing 'Ctrl-C' (the
processor will halt, leaving you in the debugger).

Simply hitting \f2RETURN\f1 at the \f2rsp>\f1 prompt will execute the last command
again. This is very handy for stepping through the execution.

Commands can be abbreviated by their shortest unique string.

The debugger commands are:

.RS 5
.TP 12
.B ! <cmd>
Executes the shell command
.B <cmd>.
.TP
.B #
Any command beginning with a '#' is a comment, and will just be echoed
back to the screen. This is useful for command source files and
breakpoint-executed commands.
.TP
.B append <file> <addr> <len>
Appends memory to a file.
.TP
.B bcopy <from> <to> <len>
This command copies memory around; <len> bytes from <from> to <to>.
This comand is most useful to simulate the "master" relationship of
the host CPU, copying memory into the IMem, etc.
.TP
.B break [<addr>] [<clk>]
Set a breakpoint. Sets a breakpoint at the current PC address, or at
<addr>. If "clk" is specified, the value of <addr> is interpreted as a
clock time, and the breakpoint will be set at that time.
.TP
.B command <bp>
Add debugger commands to be executed when breakpoint <bp> is hit. This
is useful for printing out information while debugging, etc. Remember
that a debugger command that starts with '#' is a comment, so you can
echo any text out this way. Enter the debugger commands, one per line,
and type 'end' when you are finished. If you want to delete all the
commands, just type 'end' as the first command. Editing is limited,
if you make a mistake, you'll probably have to re-type it.
.TP
.B cont
Continue execution, after stopping.
.TP
.B dbase <addr>
Set base address of data window.
.TP
.B deposit <addr> <value>
Puts <value> into the contents of the memory at <addr>. The address is
a word address, you can't specify individual bytes. (you have to
retype the bytes you don't want to change...) Scalar registers can be
specified by typing $r as the <addr>, vector registers can be specified
by typing $vr as the <addr>. Symbolic registers like pc, ctl, clk can
also be given.
.TP
.B disable <brkpt>
Disable the specified breakpoint. (Currently there is no way to
"delete" a breakpoint, other than disabling it).
.TP
.B enable <brkpt>
Enable the specified breakpoint. Turns 'on' a previously disabled breakpoint.
.TP
.B evaluate <expr>
Evaluate an expression.
.TP
.B examine <addr> [<count>]
Examine memory at <addr> for <count> bytes. Default <count> is one
word. Allows you to look at the memory.
.TP
.B file <file>
View source file.
.TP
.B help <command>
Prints a help screen. If <command> is given, prints a more verbose
message for that command.
.TP
.B info
Prints out information about the debugger state, such as current breakpoints.
.TP
.B list <addr> [<count>]
List (disassemble) the program at <addr> for <count> statements.
Default <count> is 10. A period "." can be used to specify the PC.
.TP
.B load <file> <addr>
Read bytes from <file> and copy them to memory beginning at <addr>.
This command could be used to load up a task list (program) to
execute, or data to operate on.
.TP
.B nosilent
Turns on verbose messages.
.TP
.B quit
Exit simulator.
.TP
.B register [<reg>]
Examine register <reg>, if specified, or all registers. Also displays
PC, CLK, and RSP CTL registers.
.TP
.B run
Begin execution. Things are reset and the program begins running.
.TP
.B silent
Turns off some non-critical messages.
.TP
.B source <srcfile>
Reads a file of rspsim commands, executing each one. Useful for
loading a program in a certain way and setting up the RSP state during
development.
.TP
.B step [<count>]
Step execution <count> clock ticks. Default <count> is one.
.TP
.B symboltable <file>
Load symbol table.
.TP
.B vregister [<reg>]
Examine vector register <reg>, if specified, or all vector registers.
Also displays VAC, VCO, and VCC.
.TP
.B vrint <reg>
Examine integer vector register <reg> (inteprets data as integers)
.TP
.B vrdouble <int_reg> <frac_reg>
Examine vector register pair as floating point numbers.
.TP
.B vrfrac <reg>
Examine vector register <reg> (inteprets data as fraction)
.TP
.B texamine <addr> <type>
Look at a structure in memory.
.TP
.B watch <addr>
Set a memory watchpoint. If this memory is "touched", the processor
will halt at the next clock cycle.
.TP
.B write <file> <addr> <len>
Write out the contents of memory at <addr> for <len> bytes to a file
named <file>. This will be useful for creating RDP command lists.


.SS "\f2Curses Mode\f1"
[say something here about the curses version. Window size, etc....]

.SS "\f2Graphics Mode\f1"
When
.IR rsp
is run as
.IR rspg,
the simulator is run with a graphics
interface and five windows are opened.  The \f3command input\f1 window
accepts a line of input from the user.  All commands available in text
mode are available here, plus a few outlined below.  The \f3registers\f1
window displays the processor state in a similar way as the curses
mode, with some enhancements.  The \f3command output\f1 window displays
what would have been printed in text mode.  The \f3source\f1 window
displays either the disassembled instructions of instruction memory,
or the source code corresponding to the current symbol table (see
the \f2symboltable\f1 command).  Finally, the \f3data\f1 window
displays 4096 bytes of memory, which defaults to the on-chip data memory.
.TP
.B Command Input Window
The "command input" window accepts a line of
input from the user.  The mouse pointer does not have to be
inside this window for the keystrokes to go there; it only needs to
be in one of the windows of the debugger.  The right button (when in
the "command input" window) brings up a menu of commonly used commands,
and the middle button (in any window) repeats the previous command, as
if the \f2return\f1 key had been pressed on an empty input line.  A subset
of the standard 
.IR emacs
key bindings are available.  The prefix
"M-" in the table below corresponds to the "Alt" key:

.KS
        ^A				-> beginning-of-line
        ^B				-> backward-char
        ^D				-> delete-char-or-list
        ^E				-> end-of-line
        ^F				-> forward-char
        ^N				-> down-history
        ^P				-> up-history
        ^T				-> transpose-chars
        M-b				-> backward-word
        M-d				-> delete-word
        M-f				-> forward-word
.KE
.IP
Arrow keys also work, along with Ctrl-Leftarrow and Ctrl-Rightarrow to move
by words.  A ten-command history is kept.
.TP
.B Registers Window
The "registers" window displays the current
state of the Signal Processor.  This includes the 32 scalar and 32
vector registers, the special registers (\f2e.g.\f1, the program counter),
and some other internal state information.  Every time the program
counter moves, the register window is redrawn and the changes in
the window are highlighted in cyan.  If the \f3.name\f1 directive
was used in the source file and symbol information was loaded using
the \f2symboltable\f1 command, then the registers' names appear
instead of the register numbers.  The \f2-s\f1 command-line switch
puts spaces every four digit in the vector display.
.TP
.B Command Output Window
This window displays the textual results
of commands.  The scroll-back bar can be used to review the last hundred
or so lines.  Although this window has a green cursor, it does not accept
input.
.TP
.B Source Window
The source window displays the running code.  If
no symbol information is supplied, then all 1024 instructions of
imem are disassembled, the line of the program counter is
highlighted in green, and breakpoints are highlighted in red.
The scrollbar represents all 1024 instructions and green and red bars
appear on that scale.  If symbolic information was supplied with
the \f2symboltable\f1 command, then the source code file is displayed.
Each time the program counter moves, the source window is updated
to display the new location centered in the window.
.IP
The right mouse button
brings up a menu with several options.  The first toggles between
"Silent" and "Verbose".  This option not only changes the state of
the text output (see the \f2silent\f1 and \f2nosilent\f1 commands),
but also disables and enables the updating of all of the windows in
the middle of runs.  The second option toggles between disassembling
the code and displaying the source file.  If in source-file mode, then
remaining options allow the user to display the different files for
which the debugger has symbol information.  A "(PC)" is displayed
next to the file in which the program counter is located.
.IP
Clicking on a line with the left mouse button places a breakpoint
on that line.  Clicking on a line which already has a breakpoint
toggles it between enabled and disabled; disabled breakpoints are
highlighted in dark red.
.TP
.B Data Window
The data window always displays 4096 bytes of
memory.  Although it defaults to displaying the data memory in the Signal
Processor, the \f2dbase\f1 command can be used to change the starting
address.  The right mouse button brings up a menu with which the display
mode can be selected.  The choices are hexadecimal, signed decimal,
unsigned decimal, and vector format.  The last choice is useful when
displaying data which is in the graphics vector format.  The data window
can be split or cloned.  The new window is independent of the old one,
although currently all data windows must have the same base address (as
set by the \f2dbase\f1 command).  Closing all data windows quits the
application.

.SH NOTE
Be careful of blank lines in scripts, particularly ones initiated at
start-up. Since a RETURN executes the last command, blank lines can
cause unintended behavior.

.SH "SEE ALSO"
.IR rspasm (1P)