CS 216, Lab. 1

18 January 2024

Instructions

Welcome! By now you are logged on to a computer, you are using Firefox or another web browser, and you have located this page on the cs server. In this lab you will get a sample program, run it with the SPIM simulator, and observe the results. Then fill out the form on this page. Finally, you can also practice testing and submitting a simple "hello world" program, using the testing software described in the book.

All the files you will need for this course are on linux.ubishops.ca, in the directory /home/COURSES/cs216/ In particular, "programming questions" are in subdirectory quests, examples from the book or from class are in examples. (both here and in COURSES)
Supplementary material is in notes (only here on website)

Step by step

In this course you need to work on linux, with either a "remote desktop" or a terminal interface (ssh or PuTTY)

Important! General instructions for using your Linux account.

Here you will learn various ways to work in this course.
In what follows, there are often 2 options, generally A. is "At home" and B. is at Bishop's, (where you have access to x2go)

Connection trouble? see Troubleshooting

Preliminary setup of your linux account

A few steps that you only have to do ONCE. (1-5) In all these instructions, things you type in a terminal are in fixed width font.
Do the following after your first login:

Change Password: (If you have a new account) Open a "Terminal" window, and give the following command:
passwd - to set a new password.
Pick one you can remember, but not one that somebody else could guess. You will need to give your initial password, and the new one, twice.
(You will not see anything as you type.)
Open the hidden file .bashrc in a text editor (I recommend mousepad in x2go, nano in terminal), in order to set up your account to access software for CS 216

Select and copy these five lines from here: OR in the file /home/COURSES/cs216/examples/funstuff.txt

export MIPSEXAM="/home/COURSES/cs216/mipsmark-1.1/"
export PATH="$PATH:$MIPSEXAM/bin"
alias qtspim="qtspim -noexception"
export QUESTS="/home/COURSES/cs216/quests"
alias spim="$MIPSEXAM/bin/spim -asm -noexception -file"

Paste at the end of .bashrc and save this file.
You will now be able to type short commands, described below, in a terminal window. If you have one open now (perhaps from changing your password), close it now by typing exit . The changes will take effect when you open a new terminal window.

Get the file addition.a, and save it, either
1. On your home computer, you can click on the underlined link. Your browser may ask you what to do with the file, or it may display it. In the latter case, use File/save as...
2. or on linux in your "home" directory, where you have write access.
  Copy from /home/COURSES/cs216/examples/ using the terminal command
```
cp /home/COURSES/cs216/examples/addition.a ~
```
  Tilde (~) always means your "home" directory. Dot (.) means the current directory.
Check your program for syntax errors, either
1. by opening it in Mars or QtSpim (see below)
2. OR by running spim, the mips simulator program, type in any "Terminal" window on linux
```
spim addition.a
```
  This will assemble and then run the file. Possibly there will be syntax or run time error messages, and if successful, the program output.
  Or else:
  spim , (without file name) and you will get interactive prompts.
  At the (spim) command line type variously:
Now start the QtSpim simulator (or try mars, another simulator),
to "see" what is going on inside the MIPS processor, as you step through the program.

At home: Install QtSpim or Mars, if you have not already done so, by dowloading from http://sourceforge.net/projects/spimsimulator/files/ or http://courses.missouristate.edu/kenvollmar/mars/MARS_4_5_Aug2014/Mars4_5.jar
Change QtSpim settings as follows: click on settings ->choose MIPS tab ->UNcheck box: "load trap file"
ALSO choose "simple machine" - that unchecks some other boxes.
At Bishop's: (using x2go) open a terminal window and type one of these commands: (The & leaves the terminal available)
```
qtspim addition.a &
mars &
```
The book shows the older xspim. You will see the registers on the left, and the text segment on the right. The tabs at the top allow you to switch to the data segment. (you can switch to the data segment). You can single-step and watch the registers. To set a breakpoint, right-click on a line of code, and choose set breakpoint or clear breakpoint.
Mars has a different layout, and a "built-in" editor.

You will see a window with 3 panes. Load your file (addition.a), if necessary, and they will fill up.
(positions given for qtspim)
- Registers: (on left) note PC and the general registers, R0 .. R31($r0 through $ra).
- Text segment:(on right) The program's instructions, has the format:
- Data segment: (can switch from text) format:
  [location] data values - all in hexadecimal. -- data as characters. Now you know why we will be studying hex!
- Messages. (bottom) Any errors in loading will be noted in the last pane. If there is an error about "start", you forgot to type -noexception (but you shouldn't have to if you did the setup correctly), or you started qtspim from a menu, so chabge settings for MIPS.
There is a separate window, the Console. This is where a program's output will be written.
Single step through the program (icon showing lines). You will see a blue highlight move down in the text window, showing the next instruction to be executed, and see the previous instruction appear in the message window.
Stop when the first syscall is highlighted, and fill out the form below.
Step again. syscall should be executed, and "5" should now be in the console window.
Step until the second syscall is executed, and "5 oranges" is in the console window.
Now please check the corresponding box on the form.
Submit the form! (click on the submit button) I will use this information to construct my class list, and use to send you email in the future. Type your Bishop's log-in carefully! It tells me your email address
Then continue with part 2 of lab. below ----

Answer form: This is what I observed:

Mars simulator

Mars is a nice IDE (coded in Java) that provides editing, assembly, and execution (run and step) of MIPS programs.
To invoke it, at a command prompt, Type mars &
Then open a file in the window that appears.

Mars can also be used with a file from the command line, where it runs the program, just like spim.

Some small differences in the acceptable instruction formats, what I have observed so far, and the fixes, are;

sub   $sp, 1    #requires 3 operands
sub   $sp, $sp, 1 

mul	$t0, $t1, 3     # requires 3 registers
li	$t3, 3
mul	$t0, $t1, $t3

Part 2 - testing out the mipsmark software.

Today we will try out the mipsmark software package for automated testing of assembly programs. This makes a sandwich out of your program, extracting the "meat" (what you coded) and putting it between two slices of "bread" (introductory code, sets of test data), so you start with a question file (in /quests/) that has special "start cut" and "end cut" lines. Before using this system, you need to set 2 environment variables to "point to" mipsmark. [Step 3 above] (otherwise you'll get command not found errors)

To edit, debug and test assembly language files

Get the file (for lab 1, easy.a), by copying it from the quests/ directory to wherever you plan to do your work -- your choice is your own computer, or on linux.ubishops.ca (using x2go,) for which these instructions were original written,
```
cp /home/COURSES/cs216/quests/easy.a ~
```
or your own computer, where you have installed qtspim or mars, use WinSCP in windows, or these commands in a terminal to copy from yolinux to you, and later from you to your linux home directory
```
scp  youracct@linux.ubishops.ca:/home/COURSES/cs216/quests/easy.a ~
scp  easy.a youracct@linux.ubishops.ca:~
```
note the spaces and ~ which means "my home directory.
The problem is simply to write "str" which contains "hello world".
Note: You must type your name and the solution to the problem between the dashed lines:
```
#------------- start cut --------------- 
    
#   Student: (your name)     Account: (your linux username)     
#    (start of your solution to the programming problem)

#------------- end cut ----------------- 
```

The next 2 steps can be done in Mars, see Below

Edit with a plain text editor. If you can, choose syntax highlighting, for source - MIPS assembler, -or- nano a terminal, text mode editor, very useful when working remotely.)
To find syntax errors, run spim by typing at a command prompt (terminal) on linux:
spim easy.a - This will either find syntax errors, or execute an errorless program. -or- spim and, at the (spim) prompt type:

(spim) read "easy.a" (the quotes are necessary)
(spim) quit, and fix syntax errors, until no more syntax errors are reported.
(spim) run and see what, if anything, your program writes. If not correct,

Debug using qtspim (or Mars)
Use step, breakpoint, run, etc to locate logic errors.
After making changes to your file, be sure to save, then in the QtSpim "File" menu, choose "Reinitialize and Load", select your file.
When you are satisfied the program runs, get it back to linux, and test it by typing the command mipsmark easy.a and be sure it answers OK(mipsmark writes a log entry for each test you run.)

Mars has editor built in So you can write and edit your file in the data window, and test it in the execute window.

Submit your file to me for marking as follows:
submit cs216 easy.athis should result in 2 lines,
I am going to submit ... as username-easy.a Done!

When you have passed mipsmark and submit, You have finished!

Troubleshooting:

You may get various responses from the command mipsmark :

bash: command not found -- You did not do the setup phase steps 2-4 above
cannot mark this question now -- your file is not named easy.a
file not found -- you didn't type the file name correctly in your command
Case 0....FAILS -- your program did not print "hello world", look at the file mark.log to see why.

Prepared by Lin Jensen, see also Course notes.

Given name
Family name
Your User Name - how you log in to Bishop's computers		(ends with a number. Only this needed if you already filled out this form or the sign-in on my home page)