Skip to content

Risbee v1.2.0

Latest

Choose a tag to compare

@nthnn nthnn released this 16 May 19:00

License

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, and SD)
    • 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)
  • Syscall API
    • Register handlers with SetSystemCall(code, fn).
    • Retrieve string and pointer parameters with GetStringPointer and GetPointerParam.
    • Built-in exit syscall (code 0 uses R10 for status).
  • 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
  • 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/risbee

Full 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