This lab is to help you set up and get familiar with two tools we will be using for this class: Discord, used for asking direct questions of me and the TAs; and MARS, the MIPS programming environment and simulator you will use to do your assignments for the first half of the course.

I expect you to read things. Do not skip words looking for diagrams and examples. Reading documentation is one of the most useful skills for programmers to have. Get used to it.

It might look like this is a long lab, but it’s because I write my assignments like tutorials, and everything in this lab is new to you. Just follow the directions in order and you’ll be done in no time.

PAY ATTENTION to these colored boxes. For some reason, lots of people skip them. I don’t know why! Don’t be like them! Read these!

Try this: boxes labeled “try this” are things to play around with and learn a little more. They are not required and you don’t have to turn in the code you write for these, so you can erase that code when you’re done playing around.

1. Setting up Discord

If you already have a Discord account and you joined my server and identified yourself to the bot, you can skip ahead to the next section. Otherwise, keep reading this section.

I sent an announcement on Canvas that explains how to sign up for Discord. Please click that link, read the whole thing carefully, and follow the directions exactly. If you run into problems at any point, please ask me for help.

When you are successfully identified, you should see several channels in the “Chatamari Damacy” server, like:

• #help
• #cs0447 - this is the one you will be talking about the course in!!!
• #geggneral
• #programming
• etc.

2. Using Discord effectively

First, make sure you are using Discord on your computer for this section. Asking programming questions with your phone is like trying to cut wood with a butter knife. Technically possible, but not easy.

Once you’re running Discord on your computer, you can go into a channel (like #cs0447), type a message, and hit enter/return to send it. Standard chat application stuff.

But there are two things you need to learn to do so you can ask questions effectively: how to send code and how to take and send screenshots.

2.1 Sending code

Please read this short section on “formatting code” and pay attention to the image.

Now, in the #cs0447 channel, try sending the MIPS code example on that page. To be clear, you do it like so:

1. hit the backtick ` key three times to write a triple-backtick ```
2. write mips immediately after the triple-backtick, with no spaces at all
   • at this point, the word mips used to turn green, like this:
   • but then Discord screwed something up and now it doesn’t turn green anymore:
   • just do not put a space between the ``` and the mips.
3. hit enter/return to go to the next line - just trust me, it’ll work!
4. copy and paste the MIPS code from that page
   • at this point the code should be highlighted in Fun Colors. If it’s all gray, you did the ```mips thing wrong.
5. hit enter/return to go to the next line
6. put another triple-backtick ``` to close it off
7. hit enter/return to send the message.

Done correctly, your message should look something like this, with colors:

Please get this working. Please try as many times as you need to get it working. Please ask the me for help in getting this working. Please please please please please

2.2 Sending screenshots

If you are sending something that is not code (e.g. program output, a graphical display, Something Weird MARS Is Doing), the easiest way is to send a screenshot, an image of part of your screen.

Do not use your phone camera to take a picture of your computer screen, ever. Every operating system has the ability to take perfect-quality screenshots built-in. It’s much faster and more convenient than your camera, too.

Windows users

If you are using Windows, follow these directions:

1. Hit Win+Shift+S on your keyboard, that is, hold down the Windows and Shift keys, and hit S. (S, for Screenshot.)
2. Click and drag a rectangle around the part of the screen you want to share.
3. Once you let go, the screenshot is now in your clipboard. That means you can now paste it anywhere you like.
4. Go to #cs0447 in Discord and paste into the message box at the bottom. (Try using Ctrl+V to paste!)
5. The image should appear in your message, and you can hit enter to send it.

Mac (Apple) users

If you are using a Mac, follow these directions:

1. Hit Control+Command+Shift+4, that is, ⌃⌘⇧4. I do not understand how Apple comes up with these shortcuts. I imagine their engineers have nine fingers per hand.
2. Click and drag a rectangle around the part of the screen you want to share.
3. Once you let go, the screenshot is now in your clipboard. That means you can now paste it anywhere you like.
4. Go to #cs0447 in Discord and paste into the message box at the bottom. (Try using ⌘V to paste!)
5. The image should appear in your message, and you can hit return to send it.

Linux users

idk lol you know more about it than I do

3. Getting and installing MARS

You must use my modified version of MARS! Not the one from Missouri State! Don’t just google MARS! Cmon!

Go to the Software page and download the version of MARS appropriate for your computer.

Platform-specific instructions follow:

Windows users

1. Run the .exe file you downloaded.
2. Allow it to run. (If it whines about it being “unverified” or whatever, click “More” and then “run anyway”)
3. It will install MARS. That’s all it does. It might not even seem like anything happened, but no news is good news.
4. Then open the Start menu and run it.
   • It might be on the “recently installed” list, or you can type “mars” to find it.

That should be it.

macOS (Apple) users

1. Run the .dmg file you downloaded.
2. Drag the MARS icon into the Applications folder.
3. Eject the .dmg file. (Ask for help if you don’t know how)

Now, you have to tell macOS to let you run the program. You only have to do this the first time you run MARS:

1. Go into your Applications folder.
2. Right-click the MARS icon, and click Open.
3. Click “Open Anyway” or whatever it says.
   • On newer versions of macOS, this will not work. Instead:
   • Open System Preferences
   • Go to Privacy & Security
   • Scroll down until you see the message "Mars_2247_0515" was blocked from use because it is not from an identified developer.", and click Open Anyway.
   • Then it’ll ask for your password/fingerprint…
   • …and then ask you to click Open Anyway, and then it’ll work.
     • Wow. What a pain! Aaaa!

From now on, you can just run it normally (e.g. pin it to the dock, or ⌘Space, type mars, hit enter)

Linux Users (including Chromebooks!)

You need to have a modern Java runtime environment installed. I think Java 11 is the oldest version that MARS will work with, but even that’s pretty old by now. Check with java -version.

You can run the jar file from the shell like:

java -jar Mars_2247_0515.jar

Or maybe you can just double-click it? idk

4. Hello, nothing

It is crucial that you get this section working before moving on. This is the most fundamental thing for doing work in this course. If you have any problems with this section, you need to ask me (or a TA, once we know who they are) for help immediately. I’m not kidding.

When you run MARS, it looks something like this:

Now:

1. File > New
2. In MIPS, comments start with a # sign. At the top of the file, put your full name and username in a comment.

3. Just like in Java or C, our assembly programs start at a main function. Type, don’t copy, these lines into your file.

   The .global directive is only needed for main. None of your other functions need it.

    .global main
    main:
   

   main: is a label. Labels name parts of your code; not just functions, but also loops, if-elses, variables, etc.

4. At this point, you cannot hit the assemble button. That’s because you haven’t saved. - You need to save (Ctrl+S/⌘S) the file into your personal files:
   • Windows users: your files are in C:\Users\<your username>. Desktop and Documents are in there.
   • macOS users: your files are in /Users/<your username> Desktop and Documents are in there.
   • Linux users: your files are in /home/<your username> but you probably knew that.

5. Instead of “compiling,” we “assemble” an asm program. When you assemble the program with the assemble button, it’ll switch to the Execute tab.

   

6. Now run with . In the “Run I/O” at the bottom of the screen, it’ll say

    -- program is finished running (dropped off bottom) --
   

   It’s a completely empty program that does nothing. Yay!

Try this: what error do you get if you remove the .global main line? Well now you know what to do if you see that error. :)

5. Playing with registers

Now you’ll learn how to put integers into registers and copy them around, and also to step through your program one instruction at a time.

Registers are like the CPU’s hands. Each one can contain a 32-bit value. What that value means or is is up to us, the programmers.

In Java, we have variables. We can put values into variables and copy values from one variable to another. There are analogous operations on registers in asm, but it’s not as straightforward as the = operator in Java.

Look at the register pane on the right side of the window. There are 35 registers listed, and all but gp, sp, and pc contain 0 (shown by default in hexadecimal as 0x00000000).. These are the values they are set to when your program starts.

“Immediate” means “a constant that is embedded within the instruction.”

1. Type, don’t copy, these instructions after your main: line. li stands for “load immediate”, and it puts a constant value into a register.

        li t0, 1
        li t1, 2
        li t2, 3
   

   By analogy to Java, li t0, 1 is like doing t0 = 1.

2. Assemble and run. Those t0, t1, t2 registers on the right side changed to 1, 2, and 3!
   • You may have to uncheck “Hexadecimal Values” at the bottom of the Data Segment view on the Execute tab for the values to be more readable.

3. But it was too fast to see what happened. Assemble again, but this time, step through instruction-by-instruction with the step button. Watch the values of the registers and the highlighted instruction in the text window.

   • You’ll see the registers highlighted green when they change.
   • You’ll notice that the highlighted instruction is the one that is just about to run. This trips a lot of people up! The effects of the instruction will not take place until you execute that instruction and move onto the next one.

4. But wait! You can go backwards too. Use this button: .

   • You’ll see the instructions happen in reverse, and the registers will get set back to 0.

   Stepping forward and backward one instruction at a time is extremely helpful when you first learn to program assembly. (It’s extremely helpful even when you’ve been using it for years, too.)

   Half a century ago, someone decided to use the word “move” instead of “copy” and now we’re stuck with it. Sorry!

5. Last, we can copy values between registers with the move instruction. After your lis, write these lines:

        move a0, t0
        move v0, t1
        move t2, zero
   

   • Assemble and step through. The values are copied from the register on the right into the register on the left. This is important: data is never “moved” on a computer, always copied. (What would moving it even do? What would be left in the original register? I dunno.)

   A really, really common mistake is to read move a0, t0 as “move a0 into t0”. This is backwards. Try to imagine move a0, t0 as a0 = t0 instead.

Try this: Load a hexadecimal immediate into a register, like li t0, 0xF00D. Assemble, and look at the “Code” column in the text segment. Do you see it?

Now try putting a value into the zero register. That’s its name. li zero, 10. What happens when that runs? What value is still in it? Why do you think the register is named zero then? ;o

When you step through your program, one other register changes on every instruction… step back, too. What register is that? What do you notice about its value? With “Hexadecimal Values” on, do you see its values anywhere else in the execute tab?

Errors and line numbers

A lot of newer programmers seem to think that when they get errors (either compiler/assembler errors or runtime errors), they just have to guess and infer where the error happens. Not true! Pretty much every error message you ever get in Java or MIPS tells you exactly where in your code the error is.

1. At the bottom left of the code editor in MARS, make sure this “Show Line Numbers” checkbox is checked (there is no reason to ever uncheck it):

   

2. Let’s introduce an error into our program to test this out. In the code you just wrote, change one of the moves to li. (Like, change move a0, t0 to li a0, t0.) Now assemble.

3. You’ll see an error at the bottom in the “Mars Messages” panel that looks something like this:

    Error in /path/to/your/abc123_lab1.asm line 16 column 9: "t0": operand is of incorrect type
    (expected INTEGER_16, got REGISTER_NAME)
   

   • See, there is no need to guess what part of your code is causing the problem. It says it’s on line 16 in your _lab1.asm file.
   • Then, if you double-click that error message, it takes you to that line of your code and highlights it!

4. Change that code back so it works again.

Code formatting

This applies to any language, not just assembly: do not treat code formatting as a “final step” you do to “clean things up” before submitting. It is not. Code formatting is absolutely crucial for making your code readable and understandable. Keep your code formatted nicely while you write it, not at the end.

Those of you who are already getting reliant on the “format source code” tool in VS Code: stop 😤

Go to the Materials page and look for the “MIPS style guide” in the References. Have a look at the code comparisons in particular. Here is an important rule about dealing with indentation, in any programming language:

Never use the spacebar at the beginning of a line of code to “line things up.” That is what the Tab key is for.

Go ahead. Try using the spacebar to indent your code in MARS right now. I dare you. ;)

The Tab key is what you use to indent code. You can also deindent code with Shift+Tab. Finally, you can select several lines of code and use Tab and Shift+Tab to indent and deindent them in virtually any code editor, including MARS.

Knowing all this, format and comment the code you’ve written so far so that it looks like this:

I have my editor settings (Settings > Editor) set a little different from the defaults. If your colors are different or your tabs are wider than the screenshot, that’s fine. Consistency and neatness are the most important parts of code formatting.

“Submitting”

This lab isn’t graded, but I wanna make sure you know how to submit before the first “real” lab.

1. On Canvas, go to “Assignments” and click Lab 0.
2. It will show a Gradescope thing inside the lab window. Upload your lab 0 file there.

If you need to resubmit, that’s fine, just do it again.