1 Purpose
CS 252 (Spring 17): Computer Organization
Assembly Project #1
Introduction to MIPS
due at 5pm, Wed 7 Feb 2018
In this project, you’ll be getting some basic experience with how to write assem- bly language. You will write a simple function (which we’ll name studentMain()), and in it you will perform some simple tasks.
1.1 Required Filenames to Turn in
Name your assembly language file asm1.s. 1.2 Allowable Instructions
When writing MIPS assembly, the only instructions that you are allowed to use (so far) are:
• add, addi, sub, addu, addiu
• and, andi, or, ori, xor, xori, nor • beq, bne, j
• slt, slti
• lw, lh, lb, sw, sh, sb
• la
• syscall
While MIPS has many other useful instructions (and the assembler recog- nizes many pseudo-instructions), do not use them! We want you to learn the fundamentals of how assembly language works – you can use fancy tricks after this class is over.
2 Standard Wrapper
Your code will need to define a single function, named studentMain(). Later, when you learn how to write functions, things will get more interesting; for now, you should just copy-paste the code below.
The following lines of code should be placed before your first instruction. This declares the function studentMain(), makes it available to the testcase, and then also gives the function “prologue” – that is, the basic code to start a function.
1
.globl studentMain studentMain:
addiu $sp, $sp, -24
sw $fp, 0($sp)
sw $ra, 4($sp)
addiu $fp, $sp, 20
# allocate stack space -- default of 24 here # save caller’s frame pointer # save return address # setup main’s frame pointer
The following lines of code should be placed after your last instruction; this implements the “epilogue”, which basically is the return; statement at the end of your function.
lw $ra, 4($sp) lw $fp, 0($sp) addiu $sp, $sp, 24 jr $ra
# get return address from stack # restore the caller’s frame pointer # restore the caller’s stack pointer # return to caller’s code
(Both of these pieces should be inside a .text section.) 3 Task Overview
Your code (inside the studentMain() function) will read four variables, named count, print, sanityCheck. Each is a word, and will be either 1 or 0. Each represents a single operation you might perform; load each one, and if the variable is 1, then perform that task. Note that some testcases will have you perform no tasks; others may have you perform several, or even all of them. Perform the tasks in the order listed in the spec; if you change the order, you will not pass the testcase.
In addition, you will be given four variables to read: locomotive, tender, boxcar, caboose. All are words. These will be used as the inputs to the tasks below. You may either read them all at the begining of your function, and save them in registers – or read them as-needed in each task below.
3.1 Matching the Output
You must match the expected output exactly, byte for byte. Every task ends with a blank line (if it does anything at all); do not print the blank line if you do not perform the task. (Thus, if a testcase asks you to perform no tasks, your code will print nothing at all.)
To find exactly the correct spelling, spacing, and other details, always look at the .out file for each example testcase I’ve provided. Any text in this spec is approximate; if it doesn’t match the .out file, then trust the .out file.
2
4 Task 1: Count
Ifcount==1,thentotalupall4ofthevariables(locomotive, tender, boxcar, caboose and print the total as follows: There are 3 total vehicles in the train. (Of course, replace 3 with the actual total.)
(Later, you will do some “sanity checking” of the values. Don’t do that for this task; just read and print whatever you find, even if the variables are negative or otherwise unexpected.)
5 Task 2: print
If print==1, then you will print out the value of the variables, along with descriptive text. It should look like the text below (with the appropriate values dropped in for each variable).
The output will look like the following:
The train has 3 locomotives, fueled by 1 tenders.
They are pulling 57 boxcars.
There are 1 cabooses at the end.
HINT: If you think about it, you can complete this task using only 5 string constants. You’re not required to do that – but you ought to try (to save yourself work, if nothing else).
6 Task 3: sanityCheck
If sanityCheck==1, then you will perform a “sanity check” on the train. Read the 4 variables, and print out any errors that you find. Begin the output with the message
Beginning sanity check...
and end with
Sanity check done, 3 errors found
Of course, print out the correct error count; a train with no errors should just show the two lines above (with 0 errors reported).
Perform the following checks, in this order. If the train passes a check, print out nothing (for that check); if it fails the check, print out the message provided.
• Non-Negative Values
If any of the 4 variables is negative, then print out the following message:
FAIL: One or more variables are negative. No other checks can be performed.
If you detect this error, set all 4 of the variables to exactly 999, and then
skip the rest of the checks.
3
7
• Locomotives Present
The train must have at least one locomotive. If not, print out: ERROR: No locomotives.
• Correct # of Tenders
A tender (https://en.wikipedia.org/wiki/Tender_(rail)) holds fuel and water for a steam locomotive. However, modern diesel locomotives carry their fuel on-board, and don’t use tenders.
For this program, the number of tenders must either be exactly equal to the number of locomotives, OR be zero. If it is neither of these, then print:
ERROR: Invalid number of tenders.
• Reasonable Train
A single locomotive can only pull a certain number of boxcars. If the number of boxcars is more than 16 times the number of locomotives, then print:
ERROR: Train is too heavy for the locomotives.
• Caboose
Modern trains don’t use cabooses, but in for many decades, every train had exactly one. For this program, your train must have either zero or one cabooses. If not, print out:
ERROR: Invalid number of cabooses.
Implementation Hint
One possible way to implement this project, which saves on code duplication, is to load all of the variables into registers first, before you do any checking. (Note: If you do this, you still ought to store into memory in the “copy” task, even if you also have a copy in a register.)
If you do this, then document which registers are used for each variable, with a block comment at the head of your function. Be careful not to modify any of these registers – otherwise, actions taken during one task might affect another.
8 Requirement: Don’t Assume Memory Lay- out!
It may be tempting to assume that the variables are all laid out in a particular order. Do not assume that! Your code should check the variables in the order that we state in this spec – but you must not assume that they will actually
4
be in that order in the testcase. Instead, you must use the la instruction for every variable that you load from memory.
To make sure that you don’t make this mistake, we will include testcases that have the variables in many different orders.
9 Running Your Code
You should always run your code using the grading script before you turn it in. However, while you are writing (or debugging) your code, it often handy to run the code yourself.
9.1 Running With Mars (GUI)
To launch the Mars application (as a GUI), open the JAR file that you down- loaded from the Mars website. You may be able to just double-click it in your operating system; if not, then you can run it by typing the following command:
java -jar <marsJarFileName>
This will open a GUI, where you can edit and then run your code. Put your code, plus one1 testcase, in some directory. Open your code in the Mars editor; you can edit it there. When it’s ready to run, assemble it (F3), run it (F5), or step through it one instruction at a time (F7). You can even step backwards in time (F8)!
9.1.1 Running the Mars GUI the First Time
The first time that you run the Mars GUI, you will need to go into the Settings menu, and set two options:
• Assemble all files in directory – so your code will find, and link with, the testcase
• Initialize Program Counter to ’main’ if defined-sothatthepro- gram will begin with main() (in the testcase) instead of the first line of code in your file.
9.2 Running Mars at the Command Line
You can also run Mars without a GUI. This will only print out the things that you explicitly print inside your program (and errors, of course).2 However, it’s an easy way to test simple fixes. (And of course, it’s how the grading script
1 Why can’t you put multiple testcases in the directory at the same time? As far as I can tell (though I’m just learning Mars myself), the Mars GUI only runs in two modes: either (a) it runs only one file, or (b) it runs all of the files in the same directory. If you put multiple testcases in the directory, it will get duplicate-symbol errors.
2 Mars has lots of additional options that allow you to dump more information, but I haven’t investigated them. If you find something useful, be sure to share it with the class!
5
works.) Perhaps the nicest part of it is that (unlike the GUI, as far as I can tell), you can tell Mars exactly what files you want to run – so multiple testcases in the directory is OK.
To run Mars at the command line, type the following command:
java -jar <marsJarFileName> sm <testcaseName>.s <yourSolution>.s
10 A Note About Grading
Your code will be tested automatically. Therefore, your code must:
- Use exactly the filenames that we specify (remember that names are case sensitive).
- Not use any other files (unless allowed by the project spec) – since our grading script won’t know to use them.
- Follow the spec precisely (don’t change any names, or edit the files I give you, unless the spec says to do so).
- (In projects that require output) match the required output exactly! Any extra spaces, blank lines misspelled words, etc. will cause the testcase to fail.
To make it easy to check, I have provided the grading script. I strongly recommend that you download the grading script and all of the testcases, and use them to test your code from the beginning. You want to detect any problems early on!
10.1 mips checker.pl
Like in Project 1, we’ll be checking your source code to see if it follows the rules – in this case, we’ll be checking to make sure that you don’t use any pseudoinstructions. In Project 1, we could do this with a simple grep command; in Project 2, the check requires a Perl script.
In addition to downloading grade proj02, you should also download mips checker.pl, and put it in the same directory. The grading script will call the checker script.
10.2 Testcases
You can find a set of testcases for this project at
http://lecturer-russ.appspot.com/classes/cs252/spring18/asm/asm1/
You can also find them on Lectura at
/home/russelll/cs252 website/asm/asm1/
.
For assembly language programs, the testcases will be named test *.s .
For C programs, the testcases will be named test *.c . For Java programs, 6
the testcases will be named Test *.java . (You will only have testcases for the languages that you have to actually write for each project, of course.)
Each testcase has a matching output file, which ends in .out; our grading script needs to have both files available in order to test your code.
For many projects, we will have “secret testcases,” which are additional testcases that we do not publish until after the solutions have been posted. These may cover corner cases not covered by the basic testcase, or may simply provide additional testing. You are encouraged to write testcaes of your own, in order to better test your code.
10.3 Automatic Testing
We have provided a testing script (in the same directory), named grade proj02, along with a helper script, mips checker.pl. Place both scripts, all of the testcase files (including their .out files), and your program files in the same directory. (I recommend that you do this on Lectura, or a similar department machine. It might also work on your Mac or Linux box, but no promises!)
10.4 Writing Your Own Testcases
The grading script will grade your code based on the testcases it finds in the current directory. Start with the testcases I provide – however, I encourage you to write your own as well. If you write your own, simply name your testcases using the same pattern as mine, and the grading script will pick them up.
While you normally cannot share code with friends and classmates, test- cases are the exception. We encourage you to share you testcases – ideally by posting them on Piazza. Sometimes, I may even pick your testcase up to be part of the official set, when I do the grading!
11 Turning in Your Solution
You must turn in your code using D2L, using the Assignment folder for this project. Turn in only your program; do not turn in any testcases or other files.
11.1 Late Work
I will set up a separate folder in D2L for Late work. Please do not put any files in that folder unless you intend to take a late day. (If you put files in both folders, we’ll ignore the regular folder and only use your files from the Late Day folder.)
7