README
¶
Vee-em
Overview
The VM is register-based, which means arithmetic operations work with registers directly rather than a stack. This makes it faster and more similar to how real CPUs work.
Architecture
- 32 general-purpose registers
- 512KB heap for memory operations
- 8KB stack for function calls
- Flags register (zero and negative flags)
Instruction Set
Instructions use registers as operands, though the exact format varies per instruction. Arithmetic and bitwise operations work directly on registers, since this is more efficient than stack-based approaches.
Arithmetic Operations
ADD,SUB,MUL,DIV,MOD- Standard arithmetic.- All take three registers: destination and two source operands.
- Example:
ADD r0, r1, r2computesr0 = r1 + r2
Bitwise Operations
AND,OR,XOR- Binary logic operations- Takes three registers: destination and two source operands
NOT- One's complement (bitwise negation)- Takes two registers: destination and source
ShiftLeft,ShiftRight- Logical shifts (zeros fill empty bits)- Takes three registers: destination, source, and shift amount (from register)
ShiftRightArithmetic- Arithmetic shift right (preserves sign bit)- Takes three registers: destination, source, and shift amount (from register)
Memory Operations
LoadImmediate- Load a constant value directly into a register (8-byte immediate)LoadRegister- Copy value from one register to anotherLoadMemory- Load from heap address (address in register) into registerStoreMemory- Store register value to heap address
Control Flow
JmpImmediate,JmpRegister- Unconditional jumps to address- Conditional jumps based on register value (check if a register value is zero):
JmpImmediateIfZero,JmpImmediateIfNotZero- Takes register to check + immediate address
JmpRegisterIfZero,JmpRegisterIfNotZero- Takes register to check + register with address
- Conditional jumps based on flags (set by
CMPinstruction):JmpImmediateIfEqual,JmpImmediateIfNotEqual,JmpImmediateIfGreater,JmpImmediateIfGreaterOrEqual,JmpImmediateIfLess,JmpImmediateIfLessOrEqual- Takes immediate address (no register argument, just checks flags)
JmpRegisterIfEqual,JmpRegisterIfNotEqual,JmpRegisterIfGreater,JmpRegisterIfGreaterOrEqual,JmpRegisterIfLess,JmpRegisterIfLessOrEqual- Takes register with address (checks flags)
CallImmediate,CallRegister- Function calls that push return address to stack
Return- Pop return address and jump back
Stack Operations
Push- Push register value onto stack (for function call conventions)Pop- Pop stack value into register
Other
CMP- Compares two registers and sets flags for conditional jumpsHALT- Stop VM execution gracefullyNOP- No operation
Usage
import "github.com/Dobefu/vee-em"
program := []byte{
// Your bytecode instructions here
}
v := vm.New(
program,
vm.WithMagicHeader([]byte("VEE-EM")),
)
err := v.Run()
if err != nil {
log.Fatalf("Error running VM: %s", err.Error())
}
Check out the tests in run_test.go for examples of how to construct programs.
Documentation
¶
Overview ¶
Package vm provides the VM struct.
Index ¶
Constants ¶
View Source
const HeapSize = 65536
HeapSize is the size of the heap in bytes.
View Source
const NumRegisters = 32
NumRegisters is the numbers of registers in the CPU. Please note that this has to be a power of two.
View Source
const NumRegistersMask = NumRegisters - 1
NumRegistersMask is the bitmask to use when masking a raw register.
View Source
const StackSize = 1024
StackSize is the size of the stack in bytes.
Variables ¶
This section is empty.
Functions ¶
func GetInstructionLen ¶
GetInstructionLen returns the length of the provided instruction.
Types ¶
type HostCallHandler ¶
type HostCallHandler func( functionIndex int64, arg1Reg register, numArgs register, registers [NumRegisters]int64, ) (int64, error)
HostCallHandler defines a handler for calling external functions.
type Opcode ¶
type Opcode byte
Opcode defines operation codes.
const ( // OpcodeNop does not do anything. OpcodeNop Opcode = iota // OpcodePush pushes a value onto the stack. OpcodePush // OpcodePop pops a value off the stack. OpcodePop // OpcodeLoadImmediate loads an immediate value into a register. OpcodeLoadImmediate // OpcodeLoadRegister loads a value from a register into another register. OpcodeLoadRegister // OpcodeLoadMemory loads a value from memory into a register. OpcodeLoadMemory // OpcodeStoreMemory stores a value from a register into memory. OpcodeStoreMemory // OpcodeAdd adds two values. OpcodeAdd // OpcodeSub subtracts two values. OpcodeSub // OpcodeMul multiplies two values. OpcodeMul // OpcodeDiv divides two values. OpcodeDiv // OpcodeMod takes the modulo of two values. OpcodeMod // OpcodeAND performs an AND on two values. OpcodeAND // OpcodeOR performs an OR on two values. OpcodeOR // OpcodeXOR performs an exclusive OR on two values. OpcodeXOR // OpcodeNOT performs a bitwise NOT on a value. OpcodeNOT // OpcodeShiftLeft performs a bitwise shift left on a value. OpcodeShiftLeft // OpcodeShiftRight performs a bitwise shift right (logical) on a value. OpcodeShiftRight // OpcodeShiftRightArithmetic performs a bitwise shift right (arithmetic) on a value. OpcodeShiftRightArithmetic // OpcodeCMP compares two registers and sets flags. OpcodeCMP // OpcodeJmpImmediate jumps to an address. OpcodeJmpImmediate // OpcodeJmpImmediateIfZero jumps to an address if a value is zero. OpcodeJmpImmediateIfZero // OpcodeJmpImmediateIfNotZero jumps to an address if a value is not zero. OpcodeJmpImmediateIfNotZero // OpcodeJmpImmediateIfEqual jumps to an address if flags indicate equality. OpcodeJmpImmediateIfEqual // OpcodeJmpImmediateIfNotEqual jumps to an address if flags indicate inequality. OpcodeJmpImmediateIfNotEqual // OpcodeJmpImmediateIfGreater jumps to an address if flags indicate greater than. OpcodeJmpImmediateIfGreater // OpcodeJmpImmediateIfGreaterOrEqual jumps to an address if flags indicate greater than or equal. OpcodeJmpImmediateIfGreaterOrEqual // OpcodeJmpImmediateIfLess jumps to an address if flags indicate less than. OpcodeJmpImmediateIfLess // OpcodeJmpImmediateIfLessOrEqual jumps to an address if flags indicate less than or equal. OpcodeJmpImmediateIfLessOrEqual // OpcodeJmpRegister jumps to an address in a register. OpcodeJmpRegister // OpcodeJmpRegisterIfZero jumps to an address in a register if a value is zero. OpcodeJmpRegisterIfZero // OpcodeJmpRegisterIfNotZero jumps to an address in a register if a value is not zero. OpcodeJmpRegisterIfNotZero // OpcodeJmpRegisterIfEqual jumps to an address in a register if flags indicate equality. OpcodeJmpRegisterIfEqual // OpcodeJmpRegisterIfNotEqual jumps to an address in a register if flags indicate inequality. OpcodeJmpRegisterIfNotEqual // OpcodeJmpRegisterIfGreater jumps to an address in a register if flags indicate greater than. OpcodeJmpRegisterIfGreater // OpcodeJmpRegisterIfGreaterOrEqual jumps to an address in a register if flags indicate greater than or equal. OpcodeJmpRegisterIfGreaterOrEqual // OpcodeJmpRegisterIfLess jumps to an address in a register if flags indicate less than. OpcodeJmpRegisterIfLess // OpcodeJmpRegisterIfLessOrEqual jumps to an address in a register if flags indicate less than or equal. OpcodeJmpRegisterIfLessOrEqual // OpcodeCallImmediate calls a function at an immediate address. OpcodeCallImmediate // OpcodeCallRegister calls a function at an address in a register. OpcodeCallRegister // OpcodeReturn returns from a function call. OpcodeReturn // OpcodeHostCall calls an external function defined by the host. OpcodeHostCall // OpcodeHalt stops execution of the VM. OpcodeHalt )
type Option ¶
type Option func(*VM)
Option is a function that can be used to configure the VM.
func WithHostCallHandler ¶
func WithHostCallHandler(handler HostCallHandler) Option
WithHostCallHandler sets the host call handler for the VM.
func WithMagicHeader ¶
WithMagicHeader adds a magic header to the program.
Source Files
¶
- decode_instruction.go
- get_instruction_len.go
- instruction_add.go
- instruction_and.go
- instruction_call_immediate.go
- instruction_call_register.go
- instruction_cmp.go
- instruction_div.go
- instruction_halt.go
- instruction_host_call.go
- instruction_jmp_immediate.go
- instruction_jmp_immediate_if_equal.go
- instruction_jmp_immediate_if_greater.go
- instruction_jmp_immediate_if_greater_or_equal.go
- instruction_jmp_immediate_if_less.go
- instruction_jmp_immediate_if_less_or_equal.go
- instruction_jmp_immediate_if_not_equal.go
- instruction_jmp_immediate_if_not_zero.go
- instruction_jmp_immediate_if_zero.go
- instruction_jmp_register.go
- instruction_jmp_register_if_equal.go
- instruction_jmp_register_if_greater.go
- instruction_jmp_register_if_greater_or_equal.go
- instruction_jmp_register_if_less.go
- instruction_jmp_register_if_less_or_equal.go
- instruction_jmp_register_if_not_equal.go
- instruction_jmp_register_if_not_zero.go
- instruction_jmp_register_if_zero.go
- instruction_load_immediate.go
- instruction_load_memory.go
- instruction_load_register.go
- instruction_mod.go
- instruction_mul.go
- instruction_not.go
- instruction_or.go
- instruction_pop.go
- instruction_push.go
- instruction_return.go
- instruction_shift_left.go
- instruction_shift_right.go
- instruction_shift_right_arithmetic.go
- instruction_store_memory.go
- instruction_sub.go
- instruction_xor.go
- opcode.go
- run.go
- validate_magic_header.go
- vm.go
- with_host_call_handler.go
Click to show internal directories.
Click to hide internal directories.