rvik

A RV32i simulator and assembler programmed in Java.

RV32i is a 32-bit base integer variant for the RISC-V open-source ISA designed by the University of California, Berkeley. For more information, be sure to check their website or their instruction set manual.

Objective

This project intends to build an assembler capable of assembling RV32i instructions and and an editor-like graphical interface to write and simulate RV32i programs.

Package overview

The Java source files can be found in src/, and the package structure is the following:

• instructions: Contains the RV32i instruction set and the appropiate methods to assemble and execute each instruction.

• rv32i: Main package. Contains the assembler and the compiler, that translates readable RV32i code into machine code and simulates it.

• utils: Contains miscelaneous methods and utilities that are needed for certain tasks.

This project also contains a test package with a handful of unit tests made possible with JUnit.

Dependencies

Compiling and running rvik does not require any external dependencies other than having Java (JRE) installed. However, executing unit tests in the test package does require some external libraries, specified at dependencies.txt. These libraries can easily be downloaded into the project with the Makefile:

$ make lib

This target will create a lib/ directory, in which it will automatically download the required libraries through the Maven repository.

Build and execution

Note

To run rvik, building the project yourself is not necessary. You can download the latest rvik Release .jar in the "Releases" tab. It's completely portable.

You can compile the project to create an executable .jar file by simply executing

$ make

in the repository root directory. This will create a .jar file named rvik.jar, that you can simply execute like this:

$ java -jar rvik.jar

This will open the rvik editor, in which you can write and simulate RV32i code.

make compile will just create the binary files in a directory named out/ without creating the .jar file, and make clean will delete every file generated by the Makefile.

Writing RV32i code in rvik

rvik is able to assemble RV32i code. In order to do so, it follows certain syntax rules:

• The instruction name goes first, in lower case letters.
• Separation between registers/inmmediate values is done with commas.
• Registers are speficied like this: x<register number>. Immediate values do not require the x and are specified in base-10.
• Memory offsets in load and store instructions are speficied like this: <immediate offset>(<register>)

Here are some instruction examples:

addi x1, x0, 86
sw x1, 32(x1)
lb x2, 32(x1)
beq x0, x0, 64
add x1, x2, x3

Simulating code

To run a RV32i program, once finished in the editor and saved, click the "Assemble" button. If the assembly was correct, you will be able to click the "Run" button. Each specified instruction will be executed and the data memory and register tables will be updated with the values obtained after the simulation.

Test scripts

Other than the Unit Tests, three RV32i scripts can be found in the test/ directory. These scripts serve as examples, that test every type of implemented instruction in the simulator. These scripts can easily be executed by opening them in the editor.

Helpful resources

• Repository with helpful tables and information about RISC-V Programming by John Winans: https://github.com/johnwinans/rvalp

• The RISC-V assembler and simulator I used before this one, by Benjamin Landers (TheThirdOne): https://github.com/TheThirdOne/rars

License

This repository follows the GNU General Public License (GPLv3). Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. For more information, refer to the Free Software Foundation website or read the license.