CarpVM

Based on Carp by Maxwell Bernstein. The goal of the project is to try and build a small (and decently reliable) VM from the ground up. Right now there are instructions, registers, a stack, data memory, and calls. Recursion should work.

Differences between Carp (from Maxwell Bernstein) and CarpVM

C11 with -pedantic -Wall -Wextra and a few more
Aims for zero compiler warnings in library, interpreter and tests
Completely removed use of the C preprocessor (except for #includes and few #defined constants)
OpenBSD-like KNF coding style
Uses libok with asserts instead of libtap for tests (simpler)
Cleaned-up project directory hierarchy
Less focus on portability or compiler backwards compatibility
Hooks to build, test and run the interpreter before every commit

Further goals of CarpVM

Cleanup the code and focus on correctness and simplicity
Focus on memory safety and memory management correctness (talloc)
Redesign the instruction set to offer a smaller core to build upon
Improve documentation and rationale behind the instruction set
Separate parsing into a compiler and build an intermediate bytecode
Improve error handling and exit conditions/states
Faster symbol lookup
Small main loop and focus on cache coherence
Exception mechanism

Goals from Carp's old TODO file

loadstr to read a string into memory and push address onto stack
Bounds-checking load and store instructions

Installation

Getting Carp

If you already have a local copy

git fetch
git rebase

If you don't already have a local copy

git clone

Building Carp

make
make test (optional)
make install
make clean (optional)

Use

See carp -h for help with command-line arguments.

Interpreter

Run carp your_file.carp

API

Include carp/carp_machine.h in your program
Run gcc program.c /usr/local/lib/libcarp.a -o program

Syntax

The syntax looks like most ASM with instructions, arguments and whatnot:

Function/label definitions are defined with a colon at the end of the name, like so: add:
Function calls are simple: call add, 2
Registers are not prefixed with %, like so: ax
Instruction arguments are separated by commas (though actually they don't have to be)
All words must be shorter than 10 characters long
All Carp files must end with a blank line

Example:

add:
  load -4
  load -3
  add
  pop ax
  ret

main:
  push 7
  push 9
  call add
  preg ax
  halt 0

This should print 16.

Instruction set

Opcode	Arguments	Description
HALT	exit code	Sets `ext` to given code, halts, and attempts to clean up stack, data memory, and label memory.
NOP		Does nothing. Seriously.
LOADR	reg, val	Loads given integer value into given register.
LOAD	diff	Loads value at location `fp` + diff in the stack.
STORE	diff, val	Stores value at location `fp` + diff.
MOV	dst, src	Copies contents of src register into dst register.
ADD		Pops the top two integers from the stack and pushes their sum.
SUB		Pops the top two integers from the stack and pushes the difference (lower minus upper).
MUL		Pops the top two integers from the stack and pushes their product.
MOD		Pops the top two integers from the stack and pushes lower % upper.
SHR		Pops the top two integers from the stack and pushes lower >> upper.
SHL		Pops the top two integers from the stack and pushes lower << upper.
NOT		Pops top integer from stack and pushes bitwise NOT of that integer.
XOR		Pops the top two integers from the stack and pushes bitwise XOR..
OR		Pops the top two integers from the stack and pushes bitwise OR.
AND		Pops the top two integers from the stack and pushes bitwise AND.
INCR	reg	Increments value in given register.
DECR	reg	Decrements value in given register.
INC		Increments the value at the top of the stack.
DEC		Decrements the value at the top of the stack.
PUSHR	reg	Pushes value in given register.
PUSH	val	Pushes given value.
POP	reg	Pops an integer from the stack and dumps it into given register.
CMP		Pops the top two integers from the stack and checks if equal. 0 means equal. Pushes result.
LT		Pops the top two integers from the stack and checks if lower < upper. Pushes result.
GT		Pops the top two integers from the stack and checks if lower > upper. Pushes result.
JZ	addr	Jumps to given absolute address if top of the stack is 0.
RJZ	diff	Adds differential to `ip` (relative jump) if top of the stack is 0.
JNZ	addr	Jumps to given absolute address if top of the stack is not 0.
RJNZ	diff	Adds differential to `ip` (relative jump) if top of the stack is not 0.
JMP	addr	Jumps to given absolute address unconditionally.
RJMP	diff	Adds differential to `ip` (relative jump) unconditionally.
CALL	key/addr	Save state and set IP to value in data memory at key. Function may return value in `ax`.
RET		Put top of the stack into `ax` and load previous state.
PREG	reg	Prints contents of given register.
PTOP		Peeks top of stack and prints top value.

Registers

Name	Purpose
`r0` ... `r9`	General purpose.
`ax`	Return value for user-defined function.
`bx`, `cx`, `dx`, `rx`	... something in the future. Just taking up space for now.
`ip`	Instruction pointer. Used for keeping place in code, gotos, calling, etc.
`sp`	Stack pointer.
`fp`	Frame pointer. Used to keep state for function calls.
`gbg`	Garbage register mainly used for popping.
`run`	Boolean - is machine running?
`ext`	Exit code.

License

GPLv3 - See LICENSE

nNum / carpvm