simji

SIMJI - SIMulateur de Jeu d'Instructions

SIMJI is a powerful and fast instruction set simulator (ISS) made in Golang that assemble and run MIPS-assembly programs using a convienient and simple CLI or GUI.

Table of contents

Features

Installation

• From Sources
• From a released archive

Usage

• Assembly
• Disassembly
• Virtual Machine
• Graphical User Interface

Project motivations

Features

• Fast Virtual Machine (30 000 000 it/sec in average)
• Assemble mini-MIPS-assembly files in binary
• Graphical User Interface integrated to debug and try new code
• Open source project

Installation

From sources

First step you need to install Golang.

Linux

Depending on your distribution :

sudo apt install go # Debian based distro
sudo pacman -S go # Arch based distro

Windows

Install Go using the graphical installer from the official download page.

Then check that go is working from the command line

go version # should print something

Then clone the project :

git clone https://github.com/NightlySide/SIMJI.git
cd SIMJI

Then build the project :

make # using the make file
go build . # building only using go

Warning: If you build from sources using only the go build . command, the static files for the GUI will not be bundled in the executable
In order to include those files you need first to package them into a go file using : go run github.com/markbates/pkger/cmd/pkger

Once the build is done (should not take more than several seconds) you can use the simulator using the command line :

chmod +x simji
./simji -h

From a released archive

Go to the release page and download the latest release for your operating system.

Then cd into the folder were you placed the binary file :

cd Downloads/ # For example
chmod +x simji
./simji -h

Usage

Excepting the GUI, you will always need to put a path to a file for the sim to work. Or else you will be facing this message :

Assembly

For the following examples we will take this simple assembly programs that puts the number 15 in the first register and prints its value on screen :

; program.asm
add r0, 15, r1
scall 1
stop

In order to assemble a program into binary instructions you need to use the assemble command :

# Will print the instructions in the terminal
./simji assemble program.asm

You may save the instructions in a binary file as well using the --output flag :

# Will save the content in a file
./simji assemble --output program.bin program.asm

The content of the binary file should look like that :

0x00000000	0x082001e1
0x00000001	0x90000001
0x00000002	0x00000000

Disassembly

The same way you can disassemble a binary file using the disassemble command :

./simji disassemble program.bin

Which should print something like that in the terminal :

[+] INFO: No output file specified. Printing binary to console.
add r0, 15, r1
scall 1
stop

And likewise you can save the output to an external file using the --output flag.

Virtual Machine

Using the run command, you can execute an assembled file:

./simji run program.bin

Which should print something like that in the terminal:

[SCALL 1] R1 =>  15

There are several new flags to use with the running process such as the debug --debug flag which outputs data about the processes going on like interpreting the commands and so on:

There is the option to make a cpu profile using the --cpuprofile flag if you know how to use pprof (from go tools). And finally there is the --benchmark flag to run a number of times the program in order to make statistics about the performances of the VM:

Graphical User Interface

The graphical user interface (GUI) is made using the Lorca library. For this part to work you need to have Chrome or Chromium browser installed. In fact Lorca is working like electron but instead of shipping a whole instance of chromium, it uses the one installed on your system to keep the footprint of the app small.

To start the GUI you need to provide the --gui or -g flag.

In that case all other flags are ignored :

./simji --gui
./simji -g # does the same thing

Using this command will brind the GUI :

On the other tabs you can follow the execution of the program step by step and on the last tab you can monitor how each register and each memory block is used.

From this interface you can load the program into the buffer (the editor in the GUI) where you can edit the code with syntax highlighting.

Once you are happy with the program click the "Load Buffer" button which will send the program contents to the simulator for execution.

The you can execute the program step by step or do a full run.

Documentation

The documentation is available here: https://pkg.go.dev/github.com/Nightlyside/simji.

You might need to expand the directories in order to follow the documentation for each package making this project.

Project motivations

At first this project was due for a class on Numeric Architectures at the ENSTA Bretagne Engineering School. I then took it further than what was required to pass the topic.

I chose to develop this project using Golang because I wanted to try something new, to be able to put another new tech or language to my range of skills and tools.

I wanted to insist on test coverage for this project as it always seems to be something little worked in a project.

I am quite proud of the result for a first project made in Golang and I will be happy to make something different with this language.