MIPS Emulator is a cross-platform simulator for final projects in COMP 541 (Digital Logic and Computer Design) at UNC. It simulates customized MIPS processors using memory-mapped I/O and devices, such as accelerometer, keyboard, screen, and LED. Whereas flashing the MIPS assembly project onto the FPGA board can take upwards of 10 minutes per flash, this emulator allows for instant testing and debugging.
We ported the original MIPS emulator to Java to make the program work on any OS. Credit to @jordanel, @jsettlem, @swali-unc, and @MarkovInequality for their awesome work!
curl -s "https://raw.githubusercontent.com/madiali/mips-emulator/main/src/main/sh/install.sh" | bashWhen done, restart your terminal. You should then be able to run mips-em to launch MIPS Emulator. This should print out a message and open your file browser. Skip to Usage.
If this script does not work on your computer, follow the manual steps below.
Run the following:
curl -s "https://raw.githubusercontent.com/madiali/mips-emulator/main/src/main/sh/install.sh" | sed -n '/<<< Install Java <<</q;p' | bashThis is the same as the above command but runs the script only up until it's done installing a compatible Java version and setting it as the default. This section of the script should be guaranteed to work.
Then, download the JAR file from the latest release. Run it with java -jar <path-to-mips-emulator.jar>. Running with this command avoids permission issues that may arise when double-clicking the file. Skip to Usage.
Download the JAR file from the latest release.
Then, run java -jar <path-to-mips-emulator.jar>. If this prints a message and opens your file browser, you're all set (skip to Usage)! Otherwise, your Java version is incompatible, so follow the instructions below.
You need JDK 17+ with JavaFX (GUI dependency) bundled. To download, go to Azul's website. This link includes tags for Java 17 (LTS), Windows x86_64, and JDK FX.
Download the .msi file.
Double-click the .msi.
After you run it and click Next one time, you will be on the Custom Setup screen, where you will see a red X by the text Set JAVA_HOME variable. Click on it and select Will be installed on local hard drive.
You should now see this (no red X):
Click Next and then Install (administrator permissions required). When done, click Finish.
Open PowerShell. If you already had a session running, close it and restart. Run the following:
echo $env:JAVA_HOME
java --versionYou should see something like
C:\Program Files\Zulu\zulu-17\
openjdk 17.0.8.1 2023-08-24 LTS
OpenJDK Runtime Environment Zulu17.44+53-CA (build 17.0.8.1+1-LTS)
OpenJDK 64-Bit Server VM Zulu17.44+53-CA (build 17.0.8.1+1-LTS, mixed mode, sharing)
If so, run java -jar <path-to-mips-emulator.jar>. This should print a message and open File Explorer. If so, you're all set! Continue to Usage.
Otherwise, your JAVA_HOME environment variable and java --version outputs are incorrect, or you just need to restart your computer. To set JAVA_HOME, follow this StackOverflow answer. The default installation path should be C:\Program Files\Zulu\zulu-17\, as printed above. When complete, run MIPS Emulator via java -jar, as mentioned in the previous paragraph. If this still does not work, restart your computer and try again.
Create a directory with a required project configuration .json file and
your project's .mem files. You will be prompted to load this JSON file in your file explorer when the application runs.
The directory should look like this:
CatsAndDogs
├── bmem.mem
├── CatsAndDogs.json
├── dmem.mem
├── imem.mem
└── smem.mem
Our default configuration JSON file is CatsAndDogs.json. You should download it and modify it, if necessary, for your own project.
You shouldn't need to change many fields, if any, since it uses the same memory mappings as the ones in the project specification. If your memory files are named differently from {b,d,i,s}mem.mem, then change your memory file names, or change the names in the JSON file.
The "type" fields contain the special types Keyboard, Accelerometer, etc., to tell the emulator that the values at those memory addresses (specified by the "startAddr" and/or "length" fields, if necessary) are special and should be used for I/O or other purposes. For example, type InstructionMemory tells the emulator to interpret those values as instructions to be executed.
{
"type": "InstructionMemory",
"initFile": {
"filepath": "imem.mem",
"format": "hex"
}
}CatsAndDogs.json has the special types InstructionMemory, DataMemory, BitmapMemory, ScreenMemory, Keyboard, and Accelerometer.
LED and Sound are not considered special types because they do not serve any special purpose (e.g., I/O) in the emulator. That is, the emulator does not show 12 LED's on the screen or play sound (unsupported, as of now). Thus, LED and Sound are mapped with type DataMemory at the appropriate memory addresses so that you can at least inspect the values at those memory addresses in the Other Memory tab in the emulator.
{
"type": "DataMemory",
"name": "Sound",
"startAddr": "0x10030008",
"length": 1
}
For sound, specifically, the original Windows-only MIPS Emulator can play sound, so it supports Sound as a type in the JSON. Therefore, to test sound, if you are on Windows, we would suggest downloading the original MIPS Emulator and specifying "type": "Sound" in the JSON.
If you have additional memory mappings in your project, you can create those mappings in the JSON with type DataMemory to view the values in the emulator, similar to the Sound mapping shown above. For example, see rubiks.json, which has 7 additional mappings. For example,
{
"comment": "Two sound registers to play chords.",
"type": "DataMemory",
"name": "sound_2",
"startAddr": "0x10000008",
"length": 1
}The value(s) would be displayed in the Other Memory tab.
Our emulator does not see nor support any of your Verilog code, of course, so anything handled by Verilog will not show up in the emulator. For example, if you use Verilog to generate random numbers and store them at an address, you shouldn't map that in the JSON (except maybe for documentation purposes).
This should be all you need. For advanced mapping options, see Advanced configuration.
Please report issues with MIPS emulator (e.g., bug report, feature request, usage question) at Issues.
We welcome contributions! See Contributing.
For more information about the project JSON file (i.e., all possible mapping options, which we support but don't really see a need for), see the original MIPS Emulator's README.
However, note that many example JSON files in that repository specify type Sound, which we do not support and causes our emulator to crash, so do not put "type": "Sound" in a JSON file for our emulator. In general, any JSON file that works for this project will work for the original MIPS Emulator. However, a JSON file from the original MIPS Emulator's repository that specifies "type": "Sound" will not work in this project.
Also, the original MIPS Emulator supports types AccelerometerX and AccelerometerY, which are unnecessary. As shown in our example JSON files, just use Accelerometer because Accelerometer == AccelerometerX + AccelerometerY.