Lab1 Intro to MARS

1 Objectives

Following completion of this lab you should be able to:

Determine the value stored in a register in MARS.
Determine the contents of memory in MARS.
Determine the location and contents of static data in MARS.
Run MIPS programs using MARS.
Set break points and use them for debugging in MARS.
Understand the implications of pseudo-instructions such li (Load an Immediate value into a register).
Use the R-type instructions such as add in a program.
Use the I-type instructions such as ori, lw and sw in a program.
Read, modify, and write a program in MIPS assembly language and document it properly.

2 General

This lab should be completed by each student, but you will work in collaboration with a partner assigned to you by your instructor.
Bring your text book to lab.
Read the lab instructions completely before beginning.
Appendix A (similar to Appendix A of your book) from a previous edition is also available as a pdf.
Don't hesitate to ask for help.
You will be filling in the lab questions sheet during this lab, and uploading it to gradescope. Either download the Word Doc version and add your answers, or print the web page to PDF and add answers to the PDF.
Write both your name and your partner's name on the lab question sheet

3 Installing MARS

MARS is a Java program and should work on any machine that supports a Java Virtual Machine. Download it from here or from the main MARS webpage: http://courses.missouristate.edu/KenVollmar/MARS/download.htm. We will use this program throughout the course, so put it somewhere you can keep it long term.

Example for running it from a linux command line:

> java -jar Mars4_5.jar

On Windows and MacOS you should be able to double click the .jar file.

Some help and info pages are available on the MARS webpage.

4 Get your repository

To get your git repo, you'll need the git tools installed installed. If you are using Windows and need to install git, see the git scm website. If you use a different OS, you should use the install method best for your operating system.

We'll be using Github For Education to manage repositories for this course. Read all of these instructions before you begin.
1. You'll need to create a github account, your account name should be recognizable as your RHIT username.
  1. Use the pattern: "rhit-username", for example Robert's account name would be: "rhit-williarj".
  2. Even if you already have your own personal Github account please make a course-work specific account. We don't want to have to figure out who XxXSuperLuigi2022XxX is when we're grading. If we can't figure out who you are from the username we'll assume you didn't submit the assignment.
2. Go to this url to create your repository.
3. You may be prompted to grant Github Education access to your account, grant access if asked.
4. Select your Rose username from the list of students when you create your account.
  1. If your username is not listed select the "Skip to next step" link above the list of names. Tell the instructor you did this!
5. Select "Accept this assignment" on the following page. This will create your repository copy the link on the nextpage it will look something like this: https://github.com/rhit-csse232/csse232-2021b-labs-joestudent
Check out a copy of your repository.
1. Open a terminal window. For Windows, the program Git Bash will serve as your terminal.
2. Navigate to where you want your repo. For example:
```
cd Desktop
```
3. Use this command to get your repo, adjusting for your url from above.
```
git clone https://github.com/rhit-csse232/csse232-2021b-labs-joestudent
```

5 Starting MARS

Launch MARS. A window should appear named similar to "MARS 4.5" with three panes.

The right-most pane shows the contents of the registers. At the bottom of the register list is the pc register, which tracks the address of the current instruction. The tabs at the top of the pane allow you to look at coprocessor registers. If an error occurs in your code, the simulator might automatically show you the values of the coprocessor registers. We will not use these for a while, so you should switch back to the general registers for now.
The large upper-left pane the contents of the currently loaded file. It should be blank when you start up MARS. There are two tabs at the top of the pane.
1. The Edit tab allows you to edit the currently loaded assembly file.
2. The Execute tab shows the assembled code and processor state as the code runs.
The bottom panel is the output console. The 'Mars Messages' tab displays messages from the simulator. The 'Run I/O' tab shows any messages generated from the running program.

6 Running a Program

There should be a lab01 directory in your repository. Inside, there should be a p1 folder. Inside that directory there should be a p1.asm file.
Open it in MARS, by going to File > Open. The file should appear in the editor panel.
Click the Assemble button or go to Run > Assemble to assemble the file. The assembler will translate the assembly instructions into machine code ready for execution. MARS will automatically switch to the Execute tab. The execute tab shows two views of MIPS memory: the "text segment" (the program's instructions) and the "data segment" (the data stored for the program).
1. The text segment window looks messy, but each instruction has five columns of data. The first column is a checkbox that allows us to set a breakpoint. The second is the address of the instruction. The third item is the hexadecimal representation of the machine instruction. The fourth item is (basically) the assembly language representation of the machine instruction. The fifth item (if it's present) is the actual line from the source file that generated the machine instruction.
2. The data segment window shows the contents of memory, including the stack contents. You can jump to different regions in memory using the drop-down selector. For now, we'll only be concerned with the (.data) region.
Look at the text segment tab. Notice that instructions start at address 0x00400000 and continues to address 0x00400018. Also notice that the PC (program counter) register has the value 0x0400000.

When the program is assembled, the "ori $10 $0 0x00000028" instruction will be highlighted.
Notice the value of the PC.
Notice that registers $0 and $t2 currently contain zero.
Click Run > Step or use the Step button to run the currently highlighted line. Notice that the contents of register $t2 have changed, and that the new value is shown in hexadecimal form. Finally, notice the value of the PC.
Predict the effects of executing the next three instructions (the second ori, the add, and the third ori). Answer the related question on your lab sheet.
Execute the next three instructions by clicking Run > Step three times. Did you predict correctly?
The next instruction attempts to change the value of register $0 to 40. Answer the related question on your lab sheet.
The next instruction is the syscall. Notice what happens if you single step past the syscall instruction.
Click Run > Reset or use the reset button. The register and text segment contents will return to the state prior to you running the program. This allows you to rerun the program easily.

7 Running a Second Program

Open the file at lab01/p2/p2.asm.
In turn, predict the effects of executing the first three instructions (the first ori, the lui, and the second ori). Answer the lab sheet question, then simulate their execution. Did you predict correctly?
The next instruction in the source file is the first li. Notice that it actually translates into two instructions. The reason is that the immediate cannot be represented in 16 bits. This will become more clear as we talk more about the machine language representations of the instructions).
Predict the effects of each of the two instructions and simulate their execution. Notice that the combined effect is the one intended by the assembly language programmer, except that the contents of register $1 changed. By convention, that register is reserved for the assembler's use.
The next instruction in the source file is the second li. Notice that it actually translates into a single instruction, because the immediate can be represented in 16 bits.

8 Running a Third Program

Open lab01/p3/p3.asm with MARS. Look over it, then assemble it.
Notice that the data segment has changed. The array A is stored starting at address 0x10010000. Notice that each element of the array requires 32 bits, i.e. 4 bytes, of storage, and that MARS lists four words per line, so every 32nd address is displayed. The array has 15 elements, and the variable h is stored immediately following the array, so it is at address 0x1001003c.
The first instruction in the source file is an la, which expands to lui and ori. Predict its effects and simulate it. Do the new contents of register $t1 match the assembly language programmer's intent?
Do the same for the remaining instructions in the program.

9 Writing a Program

Modify the p3.asm by completing the TODO blocks:

Add your name to the file
Compute the sum of the last three elements of the array A and store the result in a new global memory variable called total. Look at the variables A and h in p3.asm for examples of memory variables (don't change A or h). Remember that the array is zero-based and that each element requires four bytes of storage. Add your code after the existing statements in p3.asm but before instructions to exit the simulator.
Once you think your program is done, you need to run some tests to verify correctness. Enable Settings > Assemble all files in directory, then remove the comment on the line #jal runtests. Make sure your code passes all tests before you submit it. Complete the last two questions on the questions sheet now.

10 Turning It In

Submit the answers to the questions contained in the lab guide using the question sheet via gradescope, only 1 per team (make sure all team member's names are included). In gradescope you are able add your team members names to the submission, make sure you do so. When you are prompted to indicate where the "code question" is on the answer sheet, just select the first page of the assignment, you DO NOT upload code to gradescope. You can find the gradescope link on the course moodle page.
Lab code will be submitted to EVERY team member's git repository. You must include your name in a comment at the top of all files you submit. BOTH PARTNERS MUST SUBMIT CODE FOR ALL THE LABS.
1. Be sure to include your name (and on future labs your partner's name) in all of your files.
2. Open a terminal window and to navigate to your lab01/p3 folder.
3. Add the changed file with:
```
git add p3.asm
```
4. Commit the changes with a commit comment:
```
git commit -m "YOUR COMMIT MESSAGE"
```
5. Send the changes to the server:
```
git push
```
Verify that your changes were pushed correctly:
1. Navigate to your main repository directory.
2. Open a visualization of your repo with this command:
```
gitk --all &
```
3. You should see a series of file commits in the upper-left panel. The data on your machine is marked by the green label master. The data on the server is marked by the orange/green label remotes/origin/master.
4. Verify that your commit with the new p3.asm is on your local machine and also the server.

Now that you have your repo, for the next labs your will just update your repository by pulling with git pull in your repo directory.