%% -*- Mode: LATEX -*-

\documentclass[11pt]{rhitcsse}

\input{cs232_defs}
\title{Lab 1 --- \textsc{SPIM}}

\begin{document}

\maketitle

\section{Objectives}

Following completion of this lab you should be able to:
\latex{\vspace*{-\topsep}\vspace*{-\partopsep}}
\begin{itemize}{}
  \latex{\setlength{\itemsep}{0in}}
  \item Determine the value stored in a register in \textsc{SPIM}.
  \item Determine the contents of memory in \textsc{SPIM}.
  \item Determine the contents of the stack in \textsc{SPIM}.
  \item Determine the location and contents of static data in
  \textsc{SPIM}.
  \item Run \textsc{MIPS} programs using \textsc{SPIM}.
  \item Set break points and use them for debugging in \textsc{SPIM}.
  \item Use the pseudo-instructions \texttt{li} (Load an Immediate value
  into a register) and \texttt{move} (copy a register) in a program.
  \item Use the R-type instructions \texttt{add} and \texttt{sub} in a
  program.
  \item Use the I-type instructions \texttt{addi}, \texttt{lw} and
  \texttt{sw} in a program.
  \item Use the \textsc{SPIM} system calls for printing integers,
  reading integers, and exiting.
  \item Read, modify, and write a program in \textsc{MIPS} assembly
  language and document it properly.
\end{itemize}


\section{General}

\begin{itemize}
  \latex{\setlength{\itemsep}{0in}}
  \item Your grade for this lab will be based on the files that you
  turn in electronically as well as your answers to some
  \htmladdnormallink{questions}{../pdf/cs232_lab1_questions.pdf}.
  \item You must remain in lab until you complete the lab exercise or 
  the end of the lab period.
  \item Bring your text book to labs.
  \item Read the lab instructions completely before beginning.
  \item Don't hesitate to ask for help.
\end{itemize}


\section{Installing \textsc{SPIM}}
\latex{\label{sec:spim}}

\textsc{SPIM} is available for \htmladdnormallink{MS
  Windows}{../spim/spimwin.exe}\footnote{Hereafter referred to as
  windoze.} and \htmladdnormallink{dos}{../spim/spimdos.exe}.  The
\htmladdnormallink{source code}{../spim/spim6.1.tar.gz} is also
available if you'd like to run it on another architecture or OS.  Both
\htmladdnormallink{general}{../spim/spim_documentation.ps.gz} and
\htmladdnormallink{windoze specific}{../spim/spimwin.ps.gz}
documentation are available.  \htmladdnormallink{Appendix
  A}{../spim/cod-appa.pdf} of your book is also available as a pdf

\textbf{You don't want to use this version!}\\
The latest version of \textsc{SPIM} can be obtained from
\htmladdnormallink{ftp://ftp.cs.wisc.edu/pub/spim/}
{ftp://ftp.cs.wisc.edu/pub/spim/}, however it does not manage the
symbol table properly and global symbols are not included.  The result
of this is that you cannot set breakpoints to global symbols.  The
source code is available for the windoze version and \textbf{BONUS
  POINTS} will be awarded to anyone who fixes the symbol table bug.\\
\textbf{You don't want to use this version!}

Download and install \textsc{SPIM}.  You are welcome to use any OS you
like.  However, I will assume that if you are not using windoze, you
know what you are doing.  The following steps are aimed at windoze
users.  %\latex{\vspace*{-\topsep}\vspace*{-\partopsep}}
\begin{itemize}
  \latex{\setlength{\itemsep}{0in}}
  \item Download the windoze version of \textsc{SPIM} to a convenient place on
  your laptop.
  \item The windoze version is a self extracting zip.  Simply
  double-click to install it.
  \item \textsc{PCspim} (the windoze version of \textsc{SPIM}) can be
  launched by double-clicking it.
\end{itemize}


\section{Running a Program}

Examine the file \htmladdnormallink{\texttt{p1.asm}}{../labs/p1.asm}
using your favorite editor.  It contains a complete program written in
\textsc{MIPS} assembly language.  It simply places three numbers into
three registers, then exits.  You may need to use ``binary transfer
mode'' to download \texttt{p1.asm} so that proper line termination is
preserved.

To run program \texttt{pl.asm}, double-click \textsc{PCspim}.
\textsc{PCspim} uses a point-and-click interface: you just click on
the commands to make \textsc{SPIM} do what you want.  The commands are
summarized in windoze specific documentation listed \latex{in Section
  \ref{sec:spim}}\html{above}.

Once you are in \textsc{SPIM}, do the following:
\latex{\vspace*{-\topsep}\vspace*{-\partopsep}}
\begin{enumerate}
  \item Click \emph{File:Open} and select \texttt{p1.asm} to load the
  file.  If there are syntax errors, messages will appear at this
  point.  If you get an error on the first non-comment line, there is
  likely a line termination problem (CR-LF vs LF).  If you get an
  error on the last line of the file, the last line is probably
  missing the final newline.  Correct the program and reload it using
  \emph{Simulator:Reload}.  Occasionally, it may be necessary to
  completely exit \textsc{PCspim} and restart following errors.
  \item Click \emph{Simulator:Breakpoints...}, enter \texttt{main},
  and click \emph{Add} and then \emph{Close} to set a breakpoint at
  the label main.  We want to skip some initialization code that is
  executed before our program runs.
  \item Click \emph{Simulator:Go}, \emph{Ok}, and \emph{No} to run the
  simulator upto the breakpoint.
  \item Press F10 three times to step through the first three lines of
  the program.
  \item Click \emph{Window:Registers} to display register values.  Are
  the values what you expect?  Be sure that you \textbf{understand}
  and can explain what is going on.
  \item Click \emph{File:Exit} to exit \textsc{SPIM}.
\end{enumerate}


\section{Writing a Program}

Copy the code in file \texttt{p1.asm} into
\texttt{p2.asm}\footnote{\texttt{.asm} files require a newline
  character after every line of code, including the last one.  This
  brittle aspect of the parser usually shows up when copy/pasting
  code.}.  Modify \texttt{p2.asm} to compute 27 + 380 - 401 and store
the result in \$5 -- you simply need to add two more lines of code.
Load \texttt{p2.asm} into \textsc{SPIM} and test it.


\section{Register Conventions}

As we will see in the future labs, there are certain conventions for
register use.  To assist this use, \textsc{MIPS} permits registers to
be referred to by symbolic names.  For example, register \$v0 was used
in program \texttt{p1.asm}.  These conventions will be presented in
class.  For now, we will restrict ourselves to using the eight
registers labeled \$t0, \$tl, \$t2 $\ldots$ \$t7.  The \textsc{MIPS}
registers are summarized on page A-23 of your text.

Copy the code from file \texttt{p2.asm} into \texttt{p3.asm}.  Convert
all the numbered registers to t-registers.  Load \texttt{p3.asm} into
\textsc{SPIM} and test it.


\section{Register Use}

Registers are a precious commodity---they are fast, but few are
available.  Therefore, we must minimize our use of registers.

Copy the code from file \texttt{p3.asm} into \texttt{p4.asm}.  Modify
\texttt{p4.asm} to use as few registers as possible.  Do not modify
the last two lines.  These perform the system call to exit the
program.  Use only t-registers, but as few as possible.  Load
\texttt{p4.asm} into \textsc{SPIM} and test it.


\section{Printing Integers}

\textsc{SPIM} provides a small set system calls\footnote{See page A-49
  of your text for a complete list of system calls.} to make input and
output easier.  For example, there is a mechanism for printing an
integer.  The system call code is placed into register \$v0 and then
the syscall pseudo-instruction is executed.  The integer to be printed
is stored in \$a0.  For example, the following \textsc{MIPS} code will
print the integer in register \$t3.

\begin{verbatim}
        move $a0, $t3           # Coy the value of $t3 into $a0
        li   $v0, 1             # 1 is the system call code ...
        syscall                 # ... for printing an integer.
\end{verbatim} %$

Copy the code from file \texttt{p4.asm} into \texttt{p5.asm}.  Modify
\texttt{p5.asm} to print the value computed.  Load \texttt{p5.asm}
into \textsc{SPIM} and test it, but this time without a breakpoint and
without stepping - just \emph{Simulator:Go} (F5).  Click
\emph{Window:Console} and you should see the answer (6).  We will make
the output prettier in the next lab when we see how to print strings.

\section{Reading Integers}

\textsc{SPIM} also provides a mechanism for reading an integer.  Use
system call code 5, instead of code 1. When the syscall is executed,
the system will pause for input.  The integer you type (terminated
with a \textsc{Return}) will be placed into register \$v0.  You can
move that value into whatever register you choose.  For example the
following code reads and integer and stores it in register \$t0.

\begin{verbatim}
        li   $v0, 5             # 5 is the system call code ...
        syscall                 # ... for reading an integer.
        move $t0, $v0           # Copy the value read to $t3
\end{verbatim}

Copy the code from file \texttt{p5.asm} into \texttt{p6.asm}.  Modify
\texttt{p6.asm} to read\footnote{There is no prompt for the two
  inputs.  You must type those inputs on two separate lines.} two
integers and print their sum.  Load \texttt{p6.asm} into \textsc{SPIM}
and test it without a breakpoint and without stepping.


\section{Memory Access}

Download and carefully study
\htmladdnormallink{\texttt{main.asm}}{../labs/main.asm}.  Note the
coding style and documentation.  From this lab forward, you will be
expected to follow a similar coding style and to similarly document
all your work.  This program illustrates the following concepts:
%\latex{\vspace*{-\topsep}\vspace*{-\partopsep}}
\begin{enumerate}
  \item The data associated with a \textsc{MIPS} program is put into a
  data segment (preceded by \texttt{.data}) and the executable
  statements are placed in a code segment (preceded by
  \texttt{.text}).
  \item \texttt{.word} and \texttt{.asciiz} are assembler directives.
  See page A-51 and A-52 of your text for explanations.  See also page
  A-14 and A-15 for a more in-depth explanation of the
  \texttt{.asciiz} directive.
  \item The instruction \texttt{la} loads an address into a register.
  When using this instruction, you will supply a symbolic address
  (e.g. V:).
  \item The instruction \texttt{sll \$t0, \$t0, 2} multiplies the
  contents of register \$t0 by four.  \texttt{sll} stands for shift
  left logical.  Verify that shifting the contents of a register twice
  to the left (the new locations vacated to the right are filled in
  with 0's) indeed multiplies its contents by four.
  \item You can supply a symbolic base address when using the
  \texttt{lw} and \texttt{sw} instructions.
\end{enumerate}
Load and run \texttt{main.asm}.  Does it behave correctly?

Comment out the instruction \texttt{sll \$t0, \$t0, 2}. Load and run
the program again.  Does it behave correctly?  Make sure that you
\textbf{understand} the behavior of the program in these two cases.

Modify the program to do the following:
\latex{\vspace*{-\topsep}\vspace*{-\partopsep}}
\begin{enumerate}
  \item Prompt the user for an integer i between 1 and 10.
  \item Print out the ith element of the array\footnote{It is
    important to note that our arrays are zero-based.  V(2) refers to
    the third element of the array V, not the second.  However when 2
    is supplied as input, the second element is expected.} V.
\end{enumerate}


\section{Turning It In}

When the lab is complete turnin the answers to the lab questions and
upload \texttt{p6.asm} and \texttt{main.asm} to the \textit{afs} file
system at:
\begin{center}
  \texttt{/Class/cs/cs232/turnin/<}\textit{section}\texttt{>/<}%
  \textit{username}\texttt{>/lab1/}.
\end{center}
You will need your \textit{afs} password and \textit{kerberos}, the
\texttt{afs client} and \textit{aklog} from the new laptop suite.  You

\end{document}

% Local Variables:
% mode:latex
% End:
