@aloeminium108/risc-v-emulator v1.0.0

RISC-V Emulator

A RISC-V Emulator that runs on JavaScript, because Atwood's Law never fails to prove itself true.

DISCLAIMER: This package was primarily created for educational and experimental purposes. Expect bugs and missing/incomplete features.

CPU

The CPU class holds the emulation logic for a RISC-V CPU. Currently the CPU class only supports the RV32I base instruction set.

registerSet

Type: RegisterSet

Represents the 32 user-level base registers. Each register can be accessed and set by its index (0-31). Registers can be accessed or set as either signed or unsigned 32-bit integers.

This property is publicly scoped mostly for debugging purposes. In general use, there is no need to directly manipulate register values through this property.

ram

Type: DataView

View of the buffer representing the RAM that the CPU has access to. The RISC-V ISA assumes the memory system is little-endian, meaning that the least significant byte of each word is stored in the lowest address. This view is initialized from the ArrayBuffer passed to the CPU's constructor.

Direct manipulation of values in RAM is necessary for memory-mapped I/O.

pc

Type: number

Program counter. This number represents the location of the byte in RAM that the CPU is set to read an instruction from in its next execution step.

Besides debugging, this property is publicly scoped for the simulation of hardware interrupts and transfer of control to and from an operating system.

constructor(ram: ArrayBuffer, pc: number)

ram - The buffer representing the RAM that the CPU will use to execute

pc - The address in RAM that the pc should initially point to

It is expected that the ArrayBuffer passed as ram already contains whatever program is being run, and that it is large enough to contain both the machine code for the program itself and any memory addresses that may be referenced in said program.

executionStep()

Steps the CPU forward by one clock cycle. Note that because the hardware is being completely abstracted here, there is no guarantee that execution of this method will perfectly align with a single clock cycle on a physical RISC-V CPU.

RegisterSet

Sets of user-level registers are implemented as a single ArrayBuffer behind the scenes. This class is meant to enforce set register widths and encapsulate expected functionality so that registers can be accessed by index without any possibility of overflow into surrounding registers or misaligned bytes during the read/write process.

constructor(numRegisters: number)

numRegisters - The number of registers in the set

getRegister(index: number): number

index - The index of the register being accessed

returns the value of the register as a signed 32-bit integer. The register at index 0 always returns a value of 0.

getRegisterU(index: number): number

index - The index of the register being accessed

returns the value of the register as an unsigned 32-bit integer. The register at index 0 always returns a value of 0.

setRegister(index: number, value: number): number

index - The index of the register being accessed

value - The value that the register is being set to

Sets the value of the register at the specified index to value as a signed 32-bit integer. Setting the value of the register at index 0 has no effect.

setRegisterU(index: number, value: number): number

index - The index of the register being accessed

value - The value that the register is being set to

Sets the value of the register at the specified index to value as an unsigned 32-bit integer. Setting the value of the register at index 0 has no effect.

Assembler

Contains static methods for converting programs written in the RISC-V assembly language to binary machine code. These methods are currently very limited; pseudo-instructions, symbols, labels, and sections are not yet supported.

assemble(asm: string[]): ArrayBuffer

static

asm - The program in plaintext being assembled

returns an ArrayBuffer containing the entire program binary. The ArrayBuffer does not contain any space for general-purpose RAM, and so it is recommended to resize/rewrite the buffer before passing to the CPU constructor.

assembleLine(asm: string): Instruction

static

asm - The assembly instruction in plaintext being assembled

returns an Instruction object which may be recast to specific instruction types (i.e. R-Type, J-Type, etc.) for ease of manipulation and use.

This method is publicly accessible for debugging and testing purposes. In general, there is no need to directly use this method.