1whatleytay · YahyaElgabra · Dec 1, 2023 · Dec 1, 2023 · Dec 1, 2023 · Dec 1, 2023
diff --git a/coreImages/Memory.jpg b/coreImages/Memory.jpg
diff --git a/coreImages/Registers.jpg b/coreImages/Registers.jpg
diff --git a/documentation/bitmap.md b/documentation/bitmap.md
@@ -0,0 +1,66 @@
+# Bitmap Display
+The bitmap tab contains a visualization of the data stored in the designated address.
+
+![image](https://github.com/YahyaElgabra/saturn/assets/114133351/7fcbe627-4461-445e-9986-069ea79327a9)
+
+As you can see, there is a multitude of settings to change:
+**Display Width**: pixel width of the screen.
+**Display Height**: pixel height of the screen.
+**Address**: The starting address where the pixel data is stored, normally `0x10008000 ($gp)`
+
+There is also the unit settings next to the width and height, and these numbers represent how many pixels make up an unit.
+
+Below is example code to help you play around with the display.
+
+The result of running the code should look like the display above.
+
+```
+##############################################################################
+# Example: Displaying Pixels
+#
+# This file demonstrates how to draw pixels with different colours to the
+# bitmap display.
+##############################################################################
+
+######################## Bitmap Display Configuration ########################
+# - Unit width in pixels: 8
+# - Unit height in pixels: 8
+# - Display width in pixels: 256
+# - Display height in pixels: 256
+# - Base Address for Display: 0x10008000 ($gp)
+##############################################################################
+    .data
+ADDR_DSPL:
+    .word 0x10008000
+RED: .word 0xff0000
+NUM: .word 0x00000008
+    .text
+    .globl main
+
+main:
+    lw $t1, RED             # $t1 = red
+    li $t2, 0x00ff00        # $t2 = green
+    li $t3, 0x0000ff        # $t3 = blue
+    li $t4, 0xffffff        # $t4 = white
+
+    lw $t0, ADDR_DSPL       # $t0 = base address for display
+    sw $t1, 0($t0)          # paint the 1st unit (i.e., top-left) red
+    sw $t2, 4($t0)          # paint the 2nd unit on the 1st row green
+    # Notice how the next unit uses adds on 4.
+    sw $t2, 32($t0)	        # paint the 8th unit on the 1st row green
+
+
+    # Notice how the 2nd row starts on 128 because 256 width pixels / 8 pixels per unit = 32 units
+    sw $t3, 128($t0)        # paint the 1st unit on the 2nd row blue
+    sw $t2, 256($t0)        # paint the 1st unit on the 3rd row green
+    sw $t3, 384($t0)        # paint the 1st unit on the 4th row blue
+
+    lw $t5, NUM             # save NUM (8) into t5
+    add $t5, $t5, $t0       # t5 = t5 + t0 (8 + ADDR_DSPL)
+    sw $t4, ($t5)           # paint the 3rd unit on the 1st row white
+exit:
+    li $v0, 10              # terminate the program gracefully
+    syscall
+
+
+```
diff --git a/documentation/core saturn functionality.md b/documentation/core saturn functionality.md
@@ -0,0 +1,54 @@
+# Saturn Core Functionality
+
+## Introduction
+
+This document provides an overview of several different important buttons in Saturn.
+
+## Functionality
+
+![Saturn Components](./coreImages/before.png)
+*Figure 1: Saturn Components labeled before the play button is pressed*
+
+![Saturn Components](./coreImages/after.png)
+*Figure 2: Saturn Components labeled before the play button is pressed*
+
+### 1. Play
+
+The Play functionality allows you to run a program or execute a specific code snippet. By clicking the Play button, you can start the execution of your code and see the output or behavior of your program. Note that the play button will only execute code up until the first breakpoint is encountered. At this point, program execution will automatically pause. Pressing the play button again will continue program execution after this breakpoint.
+
+### 2. Pause
+
+The Pause functionality allows you to temporarily halt the execution of a running program. It is useful when you want to pause the program's execution to inspect variables or debug an issue.
+
+### 3. Stop
+
+The Stop functionality allows you to terminate the execution of a running program. Clicking the Stop button will immediately halt the program's execution and return you to the code editor.
+
+### 4. Step
+
+The Step functionality allows you to execute your code one line at a time. By clicking the Step button, you can move forward through your code, observing the changes and behavior of your program at each step.
+
+### 5. Backstep
+
+The Backstep functionality allows you to reverse the execution of your code one line at a time. By clicking the Backstep button, you can move backward through your code, undoing the changes and reverting the behavior of your program at each step.
+
+### 6. Breakpoint
+
+The Breakpoint functionality allows you to set a marker in your code for debugging purposes. By setting a breakpoint, you can pause the execution of your program at a specific line, allowing you to inspect variables, evaluate expressions, and analyze the state of your program at that point. The breakpoint can be set by clicking on the left side of a line of code. A red dot should appear when you successfully add a breakpoint to a line (see the image below).
+
+![Breakpoint Example](./coreImages/break.png)
+*Figure 3: This image shows an example of what Saturn might look like after a breakpoint has been added. In this case, a breakpoint was added to line 74.*
+
+## 7. The Console Tab
+
+In MIPS Assembly, you can print values using the following methods:
+
+1. **Print Integer**: To print an integer value, you can use the `li` (load immediate) instruction to load the value into the register `a0`, and then use the `add` instruction with register `v0` to ensure this register has the value 1 (for system call number 1). Then, include the `syscall` instruction immediately afterwards.
+
+2. **Print String**: To print a string, you can load the address of the string into the register `a0` (argument register) using the `la` (load address) instruction, and then use the `add` instruction with register `v0` to ensure this register has the value 4 (for system call number 4). Then, include the `syscall` instruction immediately afterwards.
+
+3. **Print Character**: To print a single ASCII character, you can load the address of the character into the register `a0` (argument register) using the `la` (load address) instruction, and then use the `add` instruction with register `v0` to ensure this register has the value 11 (for system call number 11). Then, include the `syscall` instruction immediately afterwards.
+
+4. **Print Hexadecimal**: To print an integer in hexidecimal, you can use the `li` (load immediate) instruction to load the value into the register `a0`, and then use the `add` instruction with register `v0` to ensure this register has the value 34 (for system call number 34). Then, include the `syscall` instruction immediately afterwards.
+
+To find more information about the system calls, you can refer to the MIPS system call documentation at https://courses.missouristate.edu/kenvollmar/mars/help/syscallhelp.html.
diff --git a/documentation/coreImages/after.png b/documentation/coreImages/after.png
diff --git a/documentation/coreImages/before.png b/documentation/coreImages/before.png
diff --git a/documentation/coreImages/break.png b/documentation/coreImages/break.png
diff --git a/documentation/debugging and console.md b/documentation/debugging and console.md
diff --git a/documentation/installation and running first file.md b/documentation/installation and running first file.md
@@ -0,0 +1,58 @@
+# Installation
+Head to the [releases](https://github.com/1whatleytay/saturn/releases) page to download the installation files.
+If you are just getting started, we recommend installing the [latest version](https://github.com/1whatleytay/saturn/releases/latest).
+For experimental use, install the [pre-release version](https://github.com/1whatleytay/saturn/releases/tag/app-v0.1.8).
+
+Follow the instructions after running the file you downloaded.
+Once completed Saturn is fully installed in your system.
+## Windows
+Download the file ending with `.msi` or `.exe`.
+## macOS
+Download the file ending with `.dmg`.
+## Linux
+Download the file ending with `.deb` or `.AppImage`.
+
+<img src=https://github.com/1whatleytay/saturn/blob/main/README-Assets.png>
+
+# Getting Started
+Once you have installed Saturn, you are ready to write your first program!
+
+After opening Saturn, there is an **Untitled** file to write in.
+
+Let's create a basic program to add and subtract 2 numbers.
+
+Every assembly program consists of 2 parts: the data and the code.
+
+Let's first create our data section with 2 variables.
+```	
+	# All memory structures are placed after the
+	# .data assembler directive
+	.data
+	# The .word assembler directive reserves space
+	# in memory for a single 4-byte word with an initial value
+value:	.word 12 		# This holds the number 12
+Z:	.word 0 		# This holds the number 0
+```
+
+Now we can write the code section using the `.text` directive.
+```
+	# All program code is placed after the
+	# .text assembler directive
+	.text 		
+	li $t2, 25		# Load immediate value (25) 
+	lw $t3, value		# Load the word stored in value (see above)
+	add $t4, $t2, $t3	# Add t4 = t2 + t3 (25 + 12) = 37 
+	sub $t5, $t2, $t3	# Subtract t5 = t2 - t3 (25 - 12) = 13
+	sw $t5, Z		# Store the answer in Z (declared above)  	
+	li $v0, 10 		# Sets $v0 to "10" to select exit syscall
+	syscall 		# Exit
+```
+
+Run the program and click on the registers tab.
+
+After scrolling down to the temporary registers, you should see 25 in $t2, 12 in $3, 37 in $t4, and 13 in $t5.
+
+![image](https://github.com/YahyaElgabra/saturn/assets/114133351/b175e9eb-538b-42a2-9fa7-c1787bd739c2)
+
+
+This program is based on this [example program](https://ecs-network.serv.pacific.edu/ecpe-170/tutorials/example1.asm/view).
diff --git a/documentation/registers and memory.md b/documentation/registers and memory.md
@@ -0,0 +1,37 @@
+# Understanding the Registers and Memory Tabs in MIPS Simulator
+
+When working with a MIPS simulator, two of the essential interfaces you'll interact with are the Registers and Memory tabs. Here's a guide to understanding and using these tabs effectively.
+
+## Registers Tab
+
+![Registers Image](../coreImages/Registers.jpg)
+
+The Registers tab displays the current values in the CPU's registers. These are categorized into several sections:
+
+- **System**: Special registers like the program counter (`pc`) and the `hi` and `lo` registers for multiplication and division operations.
+- **Values**: General-purpose registers like `$v0` and `$a0-$a3`, which are often used to hold syscall numbers and arguments.
+- **Temporary**: Registers `$t0-$t9` used for temporary storage.
+- **Saved**: Registers `$s0-$s7` used for saving important values across function calls.
+
+### Features:
+- **Reading Register Values**: You can see the current value of each register in either decimal (`Dec`) or hexadecimal (`Hex`) format.
+- **Modifying Register Values**: Some simulators allow you to modify the values of registers during debugging.
+
+### Usage Notes:
+- **Switching Between Dec/Hex Modes**: A toggle usually allows you to switch between viewing register values in decimal or hexadecimal.
+- **When Values are Available**: Register values are available and updated while the program is running. It's important to have the simulator in 'Running' mode to see the current register values.
+
+## Memory Tab
+
+![Memory Image](../coreImages/Memory.jpg)
+
+The Memory tab provides a view into the simulated machine's memory, showing contents at different addresses.
+
+### Features:
+- **Reading Memory**: The tab displays memory contents, allowing you to monitor the values stored in different memory locations.
+- **Navigating Memory**: You can jump to interesting regions, such as the `.data` section where initialized data is stored or the `.text` section which contains the compiled machine code.
+
+### Usage Notes:
+- **Understanding When Memory is Populated**: Similar to the Registers tab, the Memory tab will display information when the program is in a running state. If the program is not running or is paused, the memory contents may not reflect the current state of program execution.
+
+By familiarizing yourself with the Registers and Memory tabs, you can more effectively debug and understand the behavior of your MIPS assembly programs.