Repository navigation
Risbee is a small, self-contained virtual machine that draws inspiration from the RISC-V instruction set. Built in Go, it offers a simple and approachable way to experiment with low-level concepts like registers, memory management, and instruction decoding. With just 64 KiB of byte-addressable memory and 32 general-purpose registers, Risbee keeps its footprint minimal while still supporting a rich subset of operations—everything from basic loads and stores to arithmetic, branching, and even custom syscalls.
You don’t need to be a seasoned compiler engineer or hardware expert to get started. Risbee’s design emphasizes clarity: the VM initializes with a clear default state, lets you load a binary or raw byte slice into memory at a fixed offset, and then runs a straightforward fetch-decode-execute loop. If you want to print text, handle I/O, or integrate with your Go application in other ways, you simply register a Go function as a syscall handler, and Risbee will invoke it whenever your code calls an environment call instruction.
All you need is a Go workspace and a compiled RISC-V binary (or a simple byte array), and you’re ready to explore how a tiny VM brings machine instructions to life.
Supported Features
- Fetch-Decode-Execute Loop: Continuously fetches 32-bit little-endian instructions, decodes them by opcode/function-codes, and executes until halted.
- Instruction Support
- Loads (
LB,LH,LW,LD, and unsigned variants) - Stores (
SB,SH,SW, andSD) - Immediate ALU (
ADDI,SLTI,XORI,ORI,ANDI, and shifts) - Register-Register ALU (32/64-bit adds, subs, shifts, multiplies, divides, remainders)
- Control Flow (
BEQ,BNE,BLT,BGE,BLTU,BGEU,JAL,JALR) - Fences (no-op placeholder)
- Syscalls (via
CALL/ECALL)
- Loads (
- Syscall API
- Register handlers with
SetSystemCall(code, fn). - Retrieve string and pointer parameters with
GetStringPointerandGetPointerParam. - Built-in exit syscall (
code 0uses R10 for status).
- Register handlers with
- Memory & Registers
- 64 KiB contiguous memory (
[65536]byte) - 32 × 64-bit registers (R0 read-only zero)
- Program Counter initialized to
0x1000 - Stack Pointer (
R2) auto-set to top of memory on load
- 64 KiB contiguous memory (
- Error Handling: Invalid instructions or syscalls trigger
panic(), printing an error, setting exit code to-1, and halting.
Installation
To incorporate Risbee into your Go project, use go get:
# Install via go get
go get github.com/nthnn/risbeeFull Changelog: https://github.com/nthnn/risbee/commits/v1.0.0
Full Changelog: v1.0.0...v1.1.0
Full Changelog: v1.1.0...v1.2.0
