MIPS Interpreter

class: center, middle

# MIPS Interpreter
<br /><br />
#### Adi Yoga S. Prabawa.red[*]

.footnote[.red[*] email me at dcsaysp (at) nus.edu.sg<br />if you find any bug or you want to work on this]

---

# Workspace

.left-column[
#### Overview
]
.right-column[
.image-100[![Workspace](./img/int_02.png)]

MIPS interpreter workspace is divided into 8 areas
]

---

# Workspace

.left-column[
#### Overview
#### Input Code
]
.right-column[
.image-100[![Workspace](./img/int_03.png)]

This is where you write your MIPS program.
We are only using a [subset of MIPS operations](_interpreter.html#13).
]

---

# Workspace

.left-column[
#### Overview
#### Input Code
#### File Upload
]
.right-column[
.image-100[![Workspace](./img/int_04.png)]

Alternatively, you may also upload a MIPS program from your computer.
This interpreter is fully local.
All executions is done on your computer, so it will not actually upload anything to a server.
Instead, it will simply write your program into [Input Code](_interpreter.html#3) area.
]

---

# Workspace

.left-column[
#### Overview
#### Input Code
#### File Upload
#### Runtime Code
]
.right-column[
.image-100[![Workspace](./img/int_05.png)]

This is the code segment of your program that will be run by the interpreter, if your program passes compilation and checking.
The line number corresponds to the `pc` register in hexadecimal for easy tracing.
This area is ***readonly***.
]

---

# Workspace

.left-column[
#### Overview
#### Input Code
#### File Upload
#### Runtime Code
#### Control Buttons
]
.right-column[
.image-100[![Workspace](./img/int_06.png)]

.mediumtext[
From left to right:
1. ***Parse*** (<i class='fa fa-cog'></i>): Parse the program and display the runtime code.
2. ***Step*** (<i class='fa fa-step-forward'></i>): Execute one line of runtime code.
3. ***Play*** (<i class='fa fa-cog'></i>): Execute the program until completion (_unless program is non-terminating_).
4. ***Pause*** (<i class='fa fa-pause'></i>): Pause current execution.
5. ***Speed*** (_dropdown_): Select the speed (_instant removes any delay_).
6. ***Download*** (<i class='fa fa-download'></i>): Download the runtime code (_beautified_).
7. ***Information*** (<i class='fa fa-info'></i>): Show the information page.
]
]

---

# Workspace

.left-column[
#### Overview
#### Input Code
#### File Upload
#### Runtime Code
#### Control Buttons
#### Console & Input
]
.right-column[
.image-100[![Workspace](./img/int_07.png)]

The console area displays any error messages, program print, _etc_.
When your program prints, it will be prefixed with `>`.
If your program expects an input, there is a print prefixed with `<`.
You can put your user input in the textbox below it.
The execution will block until user input is given and keyboard button (<i class='fa fa-keyboard-o'></i>) is pressed.
]

---

# Workspace

.left-column[
#### Overview
#### Input Code
#### File Upload
#### Runtime Code
#### Control Buttons
#### Console & Input
#### Regs & Mems
]
.right-column[
.image-100[![Workspace](./img/int_08.png)]

These tables display the content of registers and memories.
There are only ***256 bytes*** of memory displayed as 4 bytes value each.
You can toggle the view between hexadecimal <sub>16</sub> and decimal <sub>10</sub>.
In each view mode, you can update the value manually (_unless the textbox is disabled_) in the respective format.
]

---

# Program

.left-column[
#### Overview
]
.right-column[
A program consists of an _optional_ data segment (_i.e.,_ `.data`) followed by a text segment (_i.e.,_ `.text`).
If no data segment is present, the header `.text` is optional.

* This is a program without data segment.
    ```asm
    addi $t0, $zero, 128
    ```

* This is an alternative program without data segment.
    ```asm
       .text
    addi $t0, $zero, 128
    ```

* This is a program with data and text.
    ```asm
       .data
    x: .word 128
       .text
    lw $t0, x
    ```
]

---

# Program

.left-column[
#### Overview
#### Data
]
.right-column[
The data segment is optional.
If it is given, it must start with `.data` on the first line.red[*].
A data consists of three components:

.mediumtext[
1. Label: The name of the data, corresponds to the address of the first element.
2. Type: `.word`, `.byte` or `.asciiz`
3. Values:
    * `.word`, `.byte`: Comma separated 32-bit (`.word`) or 8-bit (`.byte`) signed integer.
        ```asm
           .data
        x: .word 1, 2, 3, 4
        ```
    * `.asciiz`: Double-quoted string. Will be `null` terminated.
        ```asm
           .data
        s: .asciiz "text"
        ```
]

.footnote[.red[*] Unfortunately, due to how the parser is currently created, comments are only possible in the text segment.]
]

---

# Program

.left-column[
#### Overview
#### Data
#### Text
]
.right-column[
The text segment contains your program.
If data segment is given, the text segment must start with `.text`.
Otherwise, it is optional.

.mediumtext[
Hello World!
```asm
   .data
s: .asciiz "Hello World!"
   .text
main: addi $v0, $zero, 4   # for syscall: print_string
      la   $a0, s          # string to be printed
      syscall
```
]
]

---

# Program

.left-column[
#### Overview
#### Data
#### Text
#### Hello World
]
.right-column[
.image-75[![Workspace](./img/int_09.png)]

.smalltext[
1. Download the file [`HelloWorld.asm`](./Examples/HelloWorld.asm).
2. [Upload](_interpreter.html#4) your MIPS file.
    The code will be shown on [input code](_interpreter.html#3).
3. Left click on the parse button (<i class='fa fa-cog'></i>).
4. The `.text` will be shown on [runtime code](_interpreter.html#5).
    The `.data` will be added to [memory](_interpreter.html#8).
5. Change the speed to "Faster".
6. Left click on the step button (<i class='fa fa-step-forward'></i>).
7. Any [registers/memory](_interpreter.html#8) being read will be highlighted green and those being written will be highlighted yellow.
    You can click on the button labelled 10 to see the value in decimal.
8. Left click on the play button (<i class='fa fa-play'></i>).
9. Program output `> Hello World!` will be printed on the [console](_interpreter.html#7) prefixed with `>`.
    Message from interpreter will also be printed here `Program Terminated` without the prefix `>`.
]
]

---

# Program

.left-column[
#### Overview
#### Data
#### Text
#### Hello World
#### Operations
]
.right-column[
The accepted operations can be found by pressing the info button (<i class='fa fa-info'></i>).
.smalltext[
<table class="table table-sm">
  <thead class="table-secondary">
    <tr>
      <th scope="col">Arithmetic</th>
      <th scope="col">Register</th>
      <th scope="col">Immediate</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><i>Addition</i></th>
      <td><samp>add $rd, $rs, $rt</samp></td>
      <td><samp>addi $rd, $rs, C16<sub>2s</sub></samp></td>
    </tr>
    <tr>
      <th scope="row"><i>Subtraction</i></th>
      <td><samp>sub $rd, $rs, $rt</samp></td>
      <td></td>
    </tr>
    <tr>
      <th scope="row"><i>Bitwise AND</i></th>
      <td><samp>and $rd, $rs, $rt</samp></td>
      <td><samp>andi $rd, $rs, C16</samp></td>
    </tr>
    <tr>
      <th scope="row"><i>Bitwise OR</i></th>
      <td><samp>or $rd, $rs, $rt</samp></td>
      <td><samp>ori $rd, $rs, C16</samp></td>
    </tr>
    <tr>
      <th scope="row"><i>Bitwise NOR</i></th>
      <td><samp>nor $rd, $rs, $rt</samp></td>
      <td></td>
    </tr>
    <tr>
      <th scope="row"><i>Bitwise XOR</i></th>
      <td><samp>xor $rd, $rs, $rt</samp></td>
      <td><samp>xori $rd, $rs, C16</samp></td>
    </tr>
    <tr>
      <th scope="row"><i>Set on Less Than</i></th>
      <td><samp>slt $rd, $rs, $rt</samp></td>
      <td><samp>slti $rd, $rs, C16<sub>2s</sub></samp></td>
    </tr>
    <tr>
      <th scope="row"><i>Shift Left Logical</i></th>
      <td><samp>sll $rd, $rs, C5</samp></td>
      <td></td>
    </tr>
    <tr>
      <th scope="row"><i>Shift Right Logical</i></th>
      <td><samp>srl $rd, $rs, C5</samp></td>
      <td></td>
    </tr>
  </tbody>
</table>
<p>
  <samp>C16<sub>2s</sub></samp> is a 16-bit numbers (or hex pattern) interpreted as 2s-complement number.
  It will be sign-extended.
  <br />
  <samp>C16</samp> is a 16-bit numbers (or hex pattern) interpreted as unsigned number.
  It will be bit-extended.
  <br />
  <samp>C5</samp> is a 5-bit numbers interpreted as unsigned number.
  It will be bit-extended.
</p>
]
]

---

# Program

.left-column[
#### Overview
#### Data
#### Text
#### Hello World
#### Operations
]
.right-column[
The accepted operations can be found by pressing the info button (<i class='fa fa-info'></i>).
.smalltext[
<table class="table table-sm">
  <thead class="table-secondary">
    <tr>
      <th scope="col">Jump/Branch</th>
      <th scope="col">Pseudo (less than)</th>
      <th scope="col">Pseudo (greater than)</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><samp>beq $rd, $rs, label</samp></td>
      <td><samp>blt $rd, $rs, label</samp></td>
      <td><samp>bgt $rd, $rs, label</samp></td>
    </tr>
    <tr>
      <td><samp>bne $rd, $rs, label</samp></td>
      <td><samp>ble $rd, $rs, label</samp></td>
      <td><samp>bge $rd, $rs, label</samp></td>
    </tr>
    <tr>
      <td><samp>j label</samp></td>
      <td></td>
      <td></td>
    </tr>
  </tbody>
</table>
<p>
  The <i>pseudo</i> operations may not be standard and typically will be desugared into multiple operations.
</p>
<table class="table table-sm">
  <thead class="table-secondary">
    <tr>
      <th scope="col">Memory</th>
      <th scope="col">Load</th>
      <th scope="col">Store</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><i>Word (aligned)</i></th>
      <td><samp>lw $rt, offset($rs)</samp></td>
      <td><samp>sw $rt, offset($rs)</samp></td>
    </tr>
    <tr>
      <th scope="row"><i>Byte</i></th>
      <td><samp>lb $rt, offset($rs)</samp></td>
      <td><samp>sb $rt, offset($rs)</samp></td>
    </tr>
    <tr>
      <th scope="row"><i>Word (unaligned)</i></th>
      <td><samp>ulw $rt, offset($rs)</samp></td>
      <td><samp>usw $rt, offset($rs)</samp></td>
    </tr>
  </tbody>
</table>
<p>
  <i>Unaligned</i> operations may not be standard and typically will be desugared into multiple operations.
  If <samp>.data</samp> is declared, the label can be used as a base address: <samp>lw $rt, label</samp>.
</p>
]
]

---

# Program

---

# Byte-Order

Our MIPS interpreter uses _little-endian_:

"The byte with the lowest number is on the rightmost one"
We can test this using the following data segment:

```asm
      .data
byte: .byte 0, 1, 2, 3
      .text
main: lw $t0, byte
```

You will see that the memory at address `0x00` will be `0x03020100`.
This is also seen on the value of register `$t0`.

![Little-Endian](./img/int_10.png)

---

# System Calls

There are 4 implemented system calls:

<table class="table table-sm">
  <thead class="table-secondary">
    <tr>
      <th scope="col">Code</th>
      <th scope="col">Service</th>
      <th scope="col">Arguments</th>
      <th scope="col">Result</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">1</th>
      <td><samp>print_int</samp></td>
      <td><samp>$a0 =</samp> integer</td>
      <td></td>
    </tr>
    <tr>
      <th scope="row">4</th>
      <td><samp>print_string</samp></td>
      <td><samp>$a0 =</samp> addr of 1st element of string</td>
      <td></td>
    </tr>
    <tr>
      <th scope="row">5</th>
      <td><samp>read_int</samp></td>
      <td></td>
      <td>integer (in <samp>$v0</samp>)</td>
    </tr>
    <tr>
      <th scope="row">8</th>
      <td><samp>read_string</samp></td>
      <td><samp>$a0 =</samp> buffer, <samp>$a1 =</samp> length<br /></td>
      <td></td>
    </tr>
  </tbody>
</table>

Code must be given in `$v0`.
Other system calls may be added in the future.

---

class: center, middle

# End of File