\begin{mylist}
\item[{\bf NAME}]
\nopagebreak \hfill \\
\dlxsim\ - Simulator and debugger for DLX assembly programs

\item[{\bf SYNOPSIS}]
\nopagebreak \hfill \\
{\bf dlxsim}

\item[{\bf OPTIONS}]
\nopagebreak \hfill \\
{[}-al\#{]} {[}-au\#{]} {[}-dl\#{]} {[}-du\#{]} {[}-ml\#{]} {[}-mu\#{]}
	\begin{mylist}
	\item[{\bf -al\#} \hfill]Select the latency for a floating point add (in clocks).
	\item[{\bf -au\#} \hfill]Select the number of floating point add units.
	\item[{\bf -dl\#} \hfill]Select the latency for a floating point divide.
	\item[{\bf -du\#} \hfill]Select the number of floating point divide units.
	\item[{\bf -ml\#} \hfill]Select the latency for a floating point multiply.
	\item[{\bf -mu\#} \hfill]Select the number of floating point multiply units.
	\end{mylist}

\item[{\bf DESCRIPTION}]
\nopagebreak \hfill \\
\dlxsim\ is an interactive program that loads DLX assembly programs and
simulates the operation of a DLX computer on those programs.  When
\dlxsim\ starts up, it looks for a file named {\bf .dlxsim} in the
user's home directory.  If such a file exists, \dlxsim\ reads it and
processes it as a command file.  \dlxsim\ also checks for a {\bf
.dlxsim} file in the current directory, and executes the commands in
it if the file exists.  Finally, \dlxsim\ loops forever reading commands
from standard input and printing results on standard output.

\item[{\bf NUMBERS}]
\nopagebreak \hfill \\
Whenever \dlxsim\ reads a number, it will accept the number in either
decimal notation, hexadecimal notation if the first two characters of
the number are {\bf 0x} (e.g. 0x3acf), or octal notation if the first
character is {\bf 0} (e.g. 0342).  Two \dlxsim\ commands accept only
floating pointer numbers from the user; these are {\bf fget} and {\bf
fput} and will be described later.

\item[{\bf ADDRESS EXPRESSIONS}]
\nopagebreak \hfill \\
Many of {\dlxsim}'s commands take as input an expression identifying a
register or memory location.  Such values are indicated with the term
{\em address} in the command descriptions below.  Where register names
are acceptable, any of the names {\bf r0} through {\bf r31} and {\bf
f0} through {\bf f31} may be used.  The names {\bf \$0} through {\bf
\$31} may also be used (instead of {\bf r0} through {\bf r31}), but the
dollar signs are likely to cause confusion with Tcl variables, so it
is safer to use {\bf r} instead of {\bf \$}.  The name {\bf pc} may be
used to refer to the program counter.

Symbolic expressions may be used to specify memory addresses.  The
simplest form of such an expression is a number, which is interpreted
as a memory address.  More generally, address expressions may consist of
numbers, symbols (which must be defined in the assembly files
currently loaded), the operators $*$, $/$, $\%$, $+$, $-$, $<<$, $>>$, \&, $|$,
and $\uparrow$ (which have the same meanings and precedences as in C), and
parentheses for grouping.

\item[{\bf COMMANDS}]
\nopagebreak \hfill \\
In addition to all of the built-in Tcl commands, \dlxsim\ provides the following application-specific commands:

\begin{mylist}
\item[{\bf asm} {\em instruction} {[}{\em address}{]}]
\nopagebreak \hfill \\
Treats {\em instruction} as an assembly instruction and returns a
hexadecimal value equivalent to {\em
instruction}.  Some instructions, such as relative branches, will be
assembled differently depending on where in memory the instruction
will be stored.  The {\em address} argument may be used to indicate
where the instruction would be stored; if omitted, it defaults to 0.

\item[{\bf fget} {\em address} {[}{\em flags}{]}]
\nopagebreak \hfill \\
Return the values of one or more memory locations or registers.  {\em
Address} identifies a memory location or register, and {\em flags}, if
present, consists of a number and/or set of letters, all concatenated
together.  If the number is present, it indicates how many consecutive
values to print (the default is 1).  If flag characters are present,
they have the following interpretation:

\begin{mylist}
\item[{\bf d}\hfill] Print values as double precision floating point numbers.
\item[{\bf f}\hfill] Print values as single precision floating point numbers (default).
\end{mylist}

\item[{\bf fput} {\em address number} {[}{\em precision}{]}]
\nopagebreak \hfill \\
Store {\em number} in the register or memory location given by {\em
address}.  If {\em precision} is {\bf d}, the number is stored as a
double precision floating point number (in two words).  If {\em
precision} is {\bf f} or no {\em precision} is given, the number is
stored as a single precision floating point number.

\item[{\bf get} {\em address} {[}{\em flags}{]}]
\nopagebreak \hfill \\
Similar to {\bf fget} above, this command is for all types except
floating point.  If flag characters are present, they have the following
interpretation:

\begin{mylist}
\item[{\bf B}\hfill] Print values in binary.
\item[{\bf b}\hfill] When printing memory locations, treat each byte as
a separate value.
\item[{\bf c}\hfill] Print values as ASCII characters.
\item[{\bf d}\hfill] Print values in decimal.
\item[{\bf h}\hfill] When printing memory locations, treat each halfword
as a separate value.
\item[{\bf i}\hfill] Print values as instructions in the DLX assembly
language.
\item[{\bf s}\hfill] Print values as null-terminated ASCII strings.
\item[{\bf v}\hfill] Instead of printing the value of the memory location
referred to by {\em address}, print the address itself as the value.
\item[{\bf w}\hfill] When printing memory locations, treat each word as a
separate value.
\item[{\bf x}\hfill] Print values in hexadecimal (default).
\end{mylist}

To interpret numbers as single or double precision floating point, use
the {\bf fget} command.

\item[{\bf go} {[}{\em address}{]}]
\nopagebreak \hfill \\
Start simulating the DLX machine.  If {\em address} is given,
execution starts at that memory address.  Otherwise, it continues from
wherever it left off previously.  This command does not complete until
simulated execution stops.  The return value is an information string
about why execution stopped and the current state of the machine.

\item[{\bf load} {\em file file file} \ldots]
\nopagebreak \hfill \\
Read each of the given {\em files}.  Treat them as DLX assembly
language files and load memory as indicated in the files.  Code (text)
is normally loaded starting at address 0x100, but the {\bf codeStart}
variable may be used to set a different starting address.  Data is
normally loaded starting at address 0x1000, but a different starting
address may be specified in the {\bf dataStart} variable.  The return
value is either an empty string or an error message describing
problems in reading the files.  A list of directives that the loader
understands is in a later section of this manual.

\item[{\bf put} {\em address number}]
\nopagebreak \hfill \\
Store {\em number} in the register or memory location given by {\em
address}.  The return value is an empty string.  To store floating
point numbers (single or double precision), use the {\bf fput}
command.

\item[{\bf quit}\hfill]
Exit the simulator.

\item[{\bf stats} {[}{\bf reset}{]} {[}{\bf stalls}{]} {[}{\bf opcount}{]}
      {[}{\bf pending}{]} {[}{\bf branch}{]} {[}{\bf hw}{]} {[}{\bf all}{]}]
\nopagebreak \hfill \\
This command will dump various statistics collected by the simulator
on the DLX code that has been run so far.  Any combination of options
may be selected.  The options and their results are as follows:

\begin{mylist}
\item[{\bf reset} \hfill]
Reset all of the statistics.
\item[{\bf stalls} \hfill]
Show the number of load stalls and stalls while waiting for a floating
point unit to become available or for the result of a previous
operation to become available.
\item[{\bf opcount} \hfill]
Show the number of each operation that has been executed.
\item[{\bf pending} \hfill]
Show all floating point operations currently being handled by the
floating point units as well as what their results will be and where
they will be stored.
\item[{\bf branch} \hfill]
Show the percentage of branches taken and not-taken.
\item[{\bf hw} \hfill]
Show the current hardware setup for the simulated machine.
\item[{\bf all} \hfill]
Equivalent to choosing all options except {\bf reset}.  This is the default.
\end{mylist}

\item[{\bf step} {[}{\em address}{]}]
\nopagebreak \hfill \\
If no {\em address} is given, the {\bf step} command executes a single
instruction, continuing from wherever execution previously stopped.
If {\em address} is given, then the program counter is changed to
point to {\em address}, and a single instruction is executed from
there.  In either case, the return value is an information string
about the state of the machine after the single instruction has been
executed.

\item[{\bf stop} {[}{\em option args}{]}]
\nopagebreak \hfill \\
This command may take any of the forms described below:

\begin{mylist}
\item[{\bf stop}\hfill]
Arrange for execution of DLX code to stop as soon as possible.  If a
simulation isn't in progress then this command has no effect.
This command is most often used in the {\em command}
argument for the {\bf stop at} command.  Returns an empty string.

\item[{\bf stop at} {\em address} {[}{\em command}{]}]
\nopagebreak \hfill \\
Arrange for {\em command} (a \dlxsim\ command string) to be executed
whenever the memory address identified by {\em address} is read,
written, or executed.  If {\em command} is not given, it defaults to
{\bf stop}, so that execution stops whenever {\em address} is
accessed.  A stop applies to the entire word containing {\em address}:
the stop will be triggered whenever any byte of the word is accessed.
Stops are not processed during the {\bf step} commands or the first
instruction executed in a {\bf go} command.  Returns an empty string.

\item[{\bf stop info}]
\nopagebreak \hfill \\
Return information about all stops currently set.

\item[{\bf stop delete} {\em number number number} \ldots]
\nopagebreak \hfill \\
Delete each of the stops identified by the {\em number} arguments.
Each {\em number} should be an identifying number for a stop, as
printed by {\bf stop info}.  Returns an empty string.

\end{mylist}

\end{mylist}

\item[{\bf ASSEMBLY FILE FORMAT}]
\nopagebreak \hfill \\
The assembler built into \dlxsim, invoked using the {\bf load}
command, accepts standard format DLX assembly language programs.  The file is expected to contain lines of the following form:

\begin{itemize}
\item Labels are defined by a group of non-blank characters starting
with either a letter, an underscore, or a dollar sign, and followed
immediately by a colon.  They are associated with the next address to
which code in the file will be stored.  Labels can be accessed anywhere
else within that file, and in files loaded after that if the label is
declared as {\bf .global} (see below).

\item Comments are started with a semicolon, and continue to the end of the line.

\item Constants can be entered either with or without a preceding number sign.

\item The format of instructions and their operands are as shown in
the Computer Architecture book.
\end{itemize}

While the assembler is processing an assembly file, the data and
instructions it assembles are placed in memory based on either a text
(code) or data pointer.  Which pointer is used is selected not by the
type of information, but by whether the most recent directive was {\bf
.data} or {\bf .text}.  The program initially loads into the text
segment.

The assembler supports several directives which affect how it loads
the DLX's memory.  These should be entered in the place where you
would normally place the instruction and its arguments.  The
directives currently supported by \dlxsim\ are:

\begin{mylist}
\item[{\bf .align} $n$ \hfill]
Cause the next data/code loaded to be at the next higher address with
the lower $n$ bits zeroed (the next closest address greater than or
equal to the current address that is a multiple of $2^{n-1}$).

\item[{\bf .ascii} ``{\em string1}'', ``{\em string2}'', \ldots]
\nopagebreak \hfill \\
Store the {\em strings} listed on the line in memory as a list of
characters.  The strings are not terminated by a 0 byte.

\item[{\bf .asciiz} ``{\em string1}'', ``{\em string2}'', \ldots]
\nopagebreak \hfill \\
Similar to {\bf .ascii}, except each string is followed by a 0 byte
(like C strings).

\item[{\bf .byte} ``{\em byte1}'', ``{\em byte2}'', \ldots]
\nopagebreak \hfill \\
Store the {\em bytes} listed on the line sequentially in memory.

\item[{\bf .data} {[}{\em address}{]}]
\nopagebreak \hfill \\
Cause the following code and data to be stored in the data area.  If
an {\em address} was supplied, the data will be loaded starting at
that address, otherwise, the last value for the data pointer will be
used.  If we were just reading code based on the text (code) pointer,
store that address so that we can continue from there later (on a {\bf
.text} directive).

\item[{\bf .double} {\em number1}, {\em number2}, \ldots]
\nopagebreak \hfill \\
Store the {\em numbers} listed on the line sequentially in memory as
double precision floating point numbers.

\item[{\bf .float} {\em number1}, {\em number2}, \ldots]
\nopagebreak \hfill \\
Store the {\em numbers} listed on the line sequentially in memory as
single precision floating point numbers.

\item[{\bf .global} {\em label}]
\nopagebreak \hfill \\
Make the {\em label} available for reference by code found in files
loaded after this file.

\item[{\bf .space} {\em size}]
\nopagebreak \hfill \\
Move the current storage pointer forward {\em size} bytes (to leave some
empty space in memory).

\item[{\bf .text} {[}{\em address}{]}]
\nopagebreak \hfill \\
Cause the following code and data to be stored in the text (code)
area.  If an {\em address} was supplied, the data will be loaded
starting at that address, otherwise, the last value for the text
pointer will be used.  If we were just reading data based on the data
pointer, store that address so that we can continue from there later
(on a {\bf .data} directive).

\item[{\bf .word} {\em word1}, {\em word2}, \ldots]
\nopagebreak \hfill \\
Store the {\em words} listed on the line sequentially in memory.

\end{mylist}

\item[{\bf VARIABLES}]
\nopagebreak \hfill \\
\dlxsim\ uses or sets the following Tcl variables:

\begin{mylist}
\item[{\bf codeStart}]
\nopagebreak \hfill \\
If this variable exists, it indicates where to start loading code in
{\bf load} commands.

\item[{\bf dataStart}]
\nopagebreak \hfill \\
If this variable exists, it indicates where to start loading data in
{\bf load} commands.

\item[{\bf insCount}]
\nopagebreak \hfill \\
\dlxsim\ uses this variable to keep a running count of the total number
of instructions that have been simulated so far.

\item[{\bf prompt}\hfill]
If this variable exists, it should contain a \dlxsim\ command string.
\dlxsim\ will execute the command in this string before printing each
prompt, and use the result as the prompt string to print.  If this
variable doesn't exist, or if an error occurs in executing its
contents, then the prompt ``(dlxsim)'' is used.
\end{mylist}

\item[{\bf SEE ALSO}]
\nopagebreak \hfill \\
{\em Computer Architecture, A Quantitative Approach}, by~John L.~Hennessy and David A.~Patterson.

\item[{\bf KEYWORDS}]
\nopagebreak \hfill \\
DLX, debug, simulate

\end{mylist}