Awesome
THIS PROJECT IS UNSTABLE AND DEPRECATED
I have since started slow work on a more stable, better thought-out project called RabbitVM. It doesn't quite have the same level of documentation but it should work much better.
CarpVM
This is a project I've been slowly working on for about half a year now. The goal is to try and build a small (and decently reliable) VM from the ground up, learning more and more C as I go.
Right now there are instructions, registers, a stack, data memory, and calls. Not sure if recursion works... it should in theory. Haven't tested.
CONSIDER THIS PRE-ALPHA SOFTWARE. Things change more than they do in Rust!
Installation
Getting Carp
If you already have a local copy (cloned before submodule was added)
git fetchgit rebasegit submodule initgit submodule update
If you don't already have a local copy
git clone --recursive
NOTE: If git submodule status doesn't return a SHA1 hash and repository name, you have a problem.
NOTE: Recursive clone is for testing library. If not included, tests will not build.
Building Carp
makemake test(optional)make installmake clean(optional)
Tested Machines
| Arch (bit) | OS (with version, name) | Compiler (with version) |
|---|---|---|
| 64-bit | Ubuntu 12.04 (precise) | gcc 4.6.3 |
| 64-bit | Ubuntu 14.04 (trusty) | gcc 4.8.2 |
| 32-bit | Ubuntu 14.04 (trusty) | gcc 4.8.2 |
| 64-bit | OS X 10.9.4 (Mavericks) | clang 3.2 |
| 32-bit | OS X 10.9.4 (Mavericks) | gcc 4.2.1 |
| 64-bit | Arch Linux 3.13.6-1 | clang 3.4.2 |
| 64-bit? | Arch Linux 3.13.6-1 | gcc 4.9.0 20140604 |
Use
NOTE: See carp -h for help with command-line options.
Interpreter
- Write a Carp file - see SYNTAX.md. More formal spec coming.
- Run
./carp.out -f your_file.carp.
API
- Include
carp/carp_machine.hin your program. - Run
gcc program.c /usr/local/lib/libcarp.a -o program.out.
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. |
How to contribute
One way:
- Check out the TODO.md file to see if anything needs doing.
- Write some code (following existing implicit style) and submit a pull request.
Another way:
- Write some code for a feature you want to exist and submit a pull request.
License
GPLv3. See LICENSE.txt.