VM emulator and assembler written in Crystal
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
samples Add sample for OpenTechSchool Dec 7, 2016
scripts Add sample for OpenTechSchool Dec 7, 2016
spec dry up tests May 7, 2015
src Make compatible with latest Crystal Sep 30, 2016
.gitignore Fix clean target Jan 25, 2016
Makefile Fix clean target Jan 25, 2016
Projectfile Rewrite emulator in Crystal Mar 14, 2015
README.adoc Add sleep instruction Nov 14, 2015
shard.lock Use Crystal Shards Jan 25, 2016
shard.yml Upgrade assembler to newer Crystal version Aug 12, 2016

README.adoc

RCPU

RCPU is a virtual machine emulator and assembler written in Crystal.

Caution
This project is very much a work in progress.

Building

You will need Crystal to build RCPU. Once you have Crystal, run make, which will generate the compiled assembler and emulator binaries in the current directory.

Usage

To assemble a file, use rcpu-assemble, passing the input filename (with the rcs extension). This will generate a corresponding rcb file. For example:

% ./rcpu-assemble samples/fib.rcs

To run a file, use rcpu-emulate, passing the input filename (with the rcb extension). For example:

% ./rcpu-emulate samples/fib.rcb

The rcs extension is used for RCPU source files, while rcb is for RCPU binary (i.e. compiled) files.

Tests

Run make spec to compile and run the tests.

Architecture

Registers

Name Code Size (bytes) Purpose

r0

0x00

4

general-purpose

r1

0x01

4

general-purpose

r2

0x02

4

general-purpose

r3

0x03

4

general-purpose

r4

0x04

4

general-purpose

r5

0x05

4

general-purpose

r6

0x06

4

general-purpose

r7

0x07

4

general-purpose

rpc

0x08

4

program counter (a.k.a instruction pointer)

rflags

0x09

1

contains result of cmp(i)

rsp

0x0a

4

stack pointer

rbp

0x0b

4

base pointer

rr

0x0c

4

return value

Instruction format

Instructions are of variable length.

The first byte is the opcode. Register arguments are one byte long, and label/immediate arguments are four bytes long.

Instruction set

Mnemonic Opcode Arguments Effect

Function handling

call(i)

0x01, 0x02

reg/imm

ret

0x03

(none)

Stack management

push(i)

0x04, 0x05

reg/imm

push a0 onto stack

pop

0x06

reg

pop into a0

Branching

j(i)

0x07, 0x08

reg/imm

pc ← a0

je(i)

0x09, 0x0a

reg/imm

if = then pc ← a0

jne(i)

0x0b, 0x0c

reg/imm

if ≠ then pc ← a0

jg(i)

0x0d, 0x0e

reg/imm

if > then pc ← a0

jge(i)

0x0f, 0x10

reg/imm

if ≥ then pc ← a0

jl(i)

0x11, 0x12

reg/imm

if < then pc ← a0

jle(i)

0x13, 0x14

reg/imm

if ≤ then pc ← a0

Arithmetic

cmp(i)

0x15, 0x16

reg, reg/imm

(see below)

mod(i)

0x17, 0x18

reg, reg, reg/imm

a0 ← a1 % a2

add(i)

0x19, 0x1a

reg, reg, reg/imm

a0 ← a1 + a2

sub(i)

0x1b, 0x1c

reg, reg, reg/imm

a0 ← a1 - a2

mul(i)

0x1d, 0x1e

reg, reg, reg/imm

a0 ← a1 * a2

div(i)

0x1f, 0x20

reg, reg, reg/imm

a0 ← a1 / a2

xor(i)

0x21, 0x22

reg, reg, reg/imm

a0 ← a1 ^ a2

or(i)

0x23, 0x24

reg, reg, reg/imm

a0 ← a1 | a2

and(i)

0x25, 0x26

reg, reg, reg/imm

a0 ← a1 & a2

shl(i)

0x27, 0x28

reg, reg, reg/imm

a0 ← a1 << a2

shr(i)

0x29, 0x2a

reg, reg, reg/imm

a0 ← a1 >> a2

not

0x2b

reg, reg

a0 ← ~a1

Register handling

mov

0x2c

reg, reg

a0 ← a1

li

0x2d

reg, imm

a0 ← a1

Memory handling

lw

0x2e

reg, imm

(see below)

lh

0x2f

reg, imm

(see below)

lb

0x30

reg, imm

(see below)

sw

0x31

reg, imm

(see below)

sh

0x32

reg, imm

(see below)

sb

0x33

reg, imm

(see below)

Special

sleep

0xfd

imm

sleep for a0 ms

prn

0xfe

reg

print a0

halt

0xff

(none)

stops emulation

cmp(i) updates the flags register and sets the 0x01 bit to true if the arguments are equal, and the 0x02 bit to true if the first argument is greater than the second.

lw, lh and lb load data from memory into a register. lw loads a word (4 bytes), lh loads a half word (2 bytes) and lb loads a byte. Similarly, sw, sh and sb store data from a register into memory.

Several opcodes have an (i) variant. These variants take a four-byte immediate argument (meaning the data is encoded in the instruction) rather than a register name. For opcodes that have immediate variants, the Opcode column contains the non-immediate variant followed by the immediate variant.

Label arguments are identical to immediate arguments.

Memory layout

Range Use

0x00 – …

Program code

… – 0xffff

Stack (grows downward, word-aligned)

0x00010000 - 0x00014b00

Video memory (160 by 120 pixels, 1 byte per pixel)

Assembly language syntax

A lines can be an instruction line, a label line, or a data directive line. Blank lines are ignored.

Comments start with the # character and can appear anywhere on a line, including a blank line. For example:

	# load coords
	li r2, 0                 # x (in px)
	li r3, 0                 # y (in px)

An instruction line starts with a tab character, followed by the instruction mnemonic, and arguments separated by commas. For example:

	li r3, 0                 # y (in px)
	jei @print-string-done
	addi rsp, rsp, 12

Register arguments are indicated with an r prefix (e.g. rsp or r0).

Immediate values can be given in decimal (e.g. 123), in hexadecimal (starting with 0x, e.g. 0xfe), or in binary (starting with 0b, e.g. 0b10010000).

Label arguments start with the @ character.

A label line starts with an identifier, followed by a colon. For example:

print-string-loop:

A data directive line starts with a period, followed by the directive name, followed by optional arguments. For example:

.byte 0x73 # s
.byte 0x6c # l
.byte 0x65 # e
.byte 0x65 # e
.byte 0x70 # p

.word @char-left-parenthesis  # (
.word @char-right-parenthesis # )
.word @char-question-mark     # * - TODO
.word @char-question-mark     # + - TODO
.word @char-comma             # ,
.word @char-dash              # -
.word @char-period            # .
.word @char-slash             # /

The supported data directives are .byte, .half and .word; they insert a byte, a half word (two bytes) or a word (four bytes), respectively.

See the examples in the samples directory for inspiration.

To do

  • Finish implementing all opcodes

  • Tests

  • Line/column numbers in parser error messages

  • RCPU prefix in binaries