Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tekknolagi/carp

"interesting" VM in C. Let's see how this goes.
https://github.com/tekknolagi/carp

Last synced: about 2 months ago
JSON representation

"interesting" VM in C. Let's see how this goes.

Host: GitHub
URL: https://github.com/tekknolagi/carp
Owner: tekknolagi
License: gpl-3.0
Archived: true
Created: 2014-02-11T17:22:50.000Z (over 10 years ago)
Default Branch: master
Last Pushed: 2021-01-18T23:05:49.000Z (over 3 years ago)
Last Synced: 2024-06-21T18:09:38.749Z (3 months ago)
Language: C
Homepage:
Size: 415 KB
Stars: 982
Watchers: 60
Forks: 84
Open Issues: 6
Metadata Files:
- Readme: README.md
- License: LICENSE.txt

Awesome Lists containing this project

README

        # THIS PROJECT IS UNSTABLE AND DEPRECATED

I have since started slow work on a more stable, better thought-out project

called [RabbitVM](https://github.com/rabbitvm/rabbit). 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!

[![Build Status](https://travis-ci.org/tekknolagi/carp.svg?branch=master)](https://travis-ci.org/tekknolagi/carp)  

![](https://ga-beacon.appspot.com/UA-47678422-4/tekknolagi/carp)  

[![Flattr this](http://api.flattr.com/button/flattr-badge-large.png)](http://flattr.com/thing/3268893/tekknolagicarp-on-GitHub)

## Installation

### Getting Carp

**If you already have a local copy (cloned before submodule was added)**

* `git fetch`

* `git rebase`

* `git submodule init`

* `git 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

1. `make`

2. `make test` (optional)

3. `make install`

4. `make 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

1. Write a Carp file - see [SYNTAX.md](http://github.com/tekknolagi/carp/tree/master/SYNTAX.md). More formal spec coming.

2. Run `./carp.out -f your_file.carp`.

### API

1. Include `carp/carp_machine.h` in your program.

2. 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:

1. Check out the TODO.md file to see if anything needs doing.

2. Write some code (following existing implicit style) and submit a pull request.

Another way:

1. Write some code for a feature you want to exist and submit a pull request.

## License

GPLv3. See [LICENSE.txt](http://github.com/tekknolagi/carp/tree/master/LICENSE.txt).