RARS - RISC-V Assembler and Runtime Simulator
Release 1.0
August 2017
Cool Capability: Plug-in Tools
RARS is capable of running externally-developed software that interacts with an executing
program and system resources.
The requirements for such a program are:
- It implements the rars.tools.Tool interface.
- It is part of the rars.tools package.
- It compiles cleanly into a ".class" file, stored in the rars/tools directory.
RARS will detect all qualifying tools upon startup and include them in
its Tools menu.
When a tool's menu item is selected, an instance of it will be created using its no-argument
constructor and its action() method will be invoked.
If no qualifying tools are found at startup, the Tools menu will not
appear.
To use such a tool, load and assemble a program of interest then select the desired tool
from the Tools menu. The tool's window will open and depending on how it is written it will either
need to be "connected" to the program by clicking a button or will already be connected. Run
the program as you normally would, to initiate tool interaction with the executing program.
The abstract class rars.tools.AbstractToolAndApplication
is included in the RARS distribution to provide
a substantial framework for implementing your own Tool. A subclass that extends it by
implementing at least its two abstract methods can be run not only from the Tools menu but also
as a free-standing application that uses the RARS assembler and simulator in the background.
Several Tools developed by subclassing AbstractMarsToolAndApplication are included
with RARS: an Introduction to Tools, a Data Cache Simulator, a Memory Reference Visualizer, and
a Floating Point tool. The last one is quite useful even when not connected to a program
because it displays binary, hexadecimal and decimal representations for a 32 bit floating point
value; when any of them is modified the other two are updated as well.
Adding more system calls
System calls (ecall instruction) are implemented using
a technique similar to that for tools. This permits anyone to add a new syscall by defining
a new class that meets these requirements:
- It extends the rars.riscv.AbstractSyscall class.
- It is part of the rars.riscv.syscalls package.
- It compiles cleanly into a ".class" file, stored in the
rars/riscv/syscalls directory.
- An entry is added to Syscall.properties
Extending the instruction set
You can add customized pseudo-instructions to the instruction set by editing
the PseudoOps.txt. Instruction specification formats are explained in the file itself.
The specification of a pseudo-instruction is one line long. It consists of
an example of the instruction, constructed using available instruction specification symbols, followed by a semicolon-separated
list of the basic instructions it will expand to. Each is an instruction template
constructed using
instruction specification symbols combined with special template
specification symbols. The latter permit substitution at program
assembly time of operands from the user's program into the expanded
pseudo-instruction.
PseudoOps.txt is read and processed at startup, and error messages will
be produced if a specification is not correctly formatted. Note that if you wish to
edit it you first have to extract it from the JAR file.