This project contains

• A simple, stack-based virtual machine for executing low-level instructions
• An assembler supporting a Forth / PostScript like language
• An interpreter able to run compiled programs

The instructions are fixed-width at 32-bits and so are the arithmetic operands.

By default, programs have 1 million cells available for both program text and data. This means that a virtual machine memory takes up 4MB plus the data and instruction stacks.

The text and data regions are overlapped, so you can easily write self-modifying code (early versions actually required self-modification to be able to return from subroutine calls, just like Knuth's MIX, but I've since taken liberty to add such modern convenience into the core instruction set).

There are no registers. This is a stack machine, after all.

As we know from theoretical computer science, a pushdown automaton needs two stacks to be Turing equivalent. Therefore we employ two as well; one for the instruction pointer and one for the data. They live separately from the text and data region, and are only limited by the host process heap size.

The machine contains no special facilities besides this: It's inherently single-threaded and has no protection mechanisms. Its operation is completely sandboxed, though, except for access to standard output.

The project aim was to create a simple machine and language to play around with. You can benefit from it by reading the source code, playing with a language similar to Forth, but conceptually simpler, and finally by seeing how easy it is to build your own system.

The language is very similar to Forth and PostScript: You basically write in RPN --- reverse Polish notation. Anything not recognized as an instruction is put on the data stack, so to put the numbers 3 and 2 on the stack, just write

3 2

To multiply them, just append with an asterix:

3 2 * ; multiplication

This operation pops the topmost two numbers on the stack and replaces them with the result of the multiplication. To run such a program, you'd need to include the core library first, since multiplication is defined as a function:

$ cat tests/core.src your-file.src | sm
6

Labels are identifiers ending with a colon.

They refer to a particular cell in the machine, and you can access their position, value or execute code from that cell location:

label:      ; create a label for the cell at this location
&label      ; put ADDRESS of label on top of stack
&label LOAD ; put VALUE of label's cell "label" on top-of-stack
label       ; EXECUTE code from label position

So, to put the address of a label on the top of the data stack, just prepend the label name with an ampersand.

If you want the value of an address, put the address on the TOS (top of stack) and use the LOAD instruction to replace the TOS with the value at the given cell location.

When executing code at a given label position, the machine first puts the address of the next instruction on top of the instruction stack. This way you can return from a function call by using the instruction POPIP:

main:       ; program start
  print-dot
  print-dot
  HALT

print-dot:
  '.' OUT
  '\n' OUT
  POPIP     ; return from "function"

An idiom for creating variables is to create labels and putting a NOP at that location to reserve one memory cell to hold variables. An example of using a counter variable to implement a loop is given below.

counter: NOP                     ; reserve 1 word for the variable "counter"

program: 2 &counter STOR                       ; set counter to two
         &counter LOAD 1 ADD &counter STOR     ; increment counter by one

; loop counter+1 times

display: '\n' '*' OUT OUT                      ; print an asterix
         1 &counter LOAD SUB &counter STOR     ; decrement counter by one
         &display &counter LOAD JNZ            ; jump to display if not zero

The output of the above program is three stars:

$ ./sm foo.src
*
*
*

You can forward-reference labels. In fact, another idiom is to jump to the main part of the program at the start of the source.

You can do 72 OUT to print the letter "H" (72 is the ASCII code for "H"). Cutting to the chase, a program to print "Hello!" would be:

; Labels are written as a name without whitespace
; and a colon at the end.

main:
   72 out          ; "H"
  101 out          ; "e"
  108 dup out out  ; "ll"
  111 out          ; "o"
   33 out          ; "!"

  ; newline
  '\n' out

  42 outnum     ; print a number
  '\n' out      ; and newline

  ; stop program
  halt

Notice the use of the HALT instruction to stop the program.

I've implemented a multiplication function in the core library in tests/core.src:

mul:            ; ( a b -- (a*b) )
  mul-res: nop  ; placeholder for result
  mul-cnt: nop  ; placeholder for counter
  mul-num: nop

  &mul-cnt stor ; b to cnt
  dup
  &mul-res stor ; a to res
  &mul-num stor ; and to num

  mul-loop:
    ; calculate res += a
    &mul-res load
    &mul-num load +
    &mul-res stor

    ; decrement counter
    &mul-cnt load
    -1
    &mul-cnt stor

    ; loop until counter is zero
    &mul-cnt load
    &mul-loop swap -1 jnz

  &mul-res load
  popip

; ...

*:        ; alias for mul
  mul
  popip

Note that this function needs definitions for the functions + and -1.

Recall the program to multiply two numbers. Put the following in a file hey.src:

3 2 * outnum
'\n' out
halt

If we concatenate the core library with our program, we get:

$ cat tests/core.src hey.src | ./sm
6

You could implement the whole program without depending on the core library:

; semi-obfuscated multiply and print
; does not depend on any libraries

; re-inventing the wheel can be very educational!

main:
  12345 67890 * outnum
  '\n' out
  halt

; multiplication function w/inner loop
*:
  R: nop C: nop N: nop
  &C stor dup &R stor &N stor

  *-loop:
    &R load &N load add &R stor
    1 &C load sub &C stor
    &C load &*-loop swap 1 swap sub jnz

  &R load
  popip

While implementing the Karatsuba algorithm should be quite easy, Toom-Cook multiplication is left as an exercise for the reader.

I think I need to clarify that this project is actually not a joke. Fun, absolutely, but not a joke.

I just wanted to create a simple virtual machine and from that I grew a language. It's very similar to Forth and PostScript, and we all know those are extremely powerful --- particularly Forth!

Building stuff yourself is a powerful way of learning.

The following is a program to generate and print Fibonacci numbers, taken from tests/fib.src:

; Print the well-known Fibonacci sequence
;
; Our word size is only 32-bits, so we can't
; count very far.

; Program starts at main, so jump there

&main jmp

; Create label 'count', which refers to this memory
; address.
;
; The NOP (no operation; do nothing) is only used
; to reserve memory space for a variable.

count:
  nop

; Initialize the counter by storing 46 at the address of 'count'.
;
; POPIP will pop the instruction pointer, effectively jumping to
; the next location (probably the caller).

count-init:
  46 &count stor
  popip

; Shorthand for loading the number at 'count' onto the top of the stack.
;
; The "( -- counter)" comment is similar to Forth's comments, explaining
; that no number is expected on the stack, and after running this function,
; a number ("counter") will be on the stack.

count-get: ; ( -- counter )
  &count load     ; load number
  popip

; Shorthand for decrementing the number on the stack

dec: ; ( a -- a-1 )
  1 swap sub
  popip

; Store top of stack to 'count', do not alter stack

count-set: ; ( counter -- counter )
  dup &count stor
  popip

; Decrement counter and return it

count-dec: ; ( -- counter )
  count-get dec
  count-set
  popip

; Print number with a newline without altering stack

show: ; ( number -- number )
  dup outnum
  '\n' out
  popip

; Duplicate two top-most numbers on stack

dup2: ; ( a b -- a b a b )
  swap       ; b a
  dup        ; b a a
  rol3       ; a a b
  dup        ; a a b b
  rol3       ; a b b a
  swap       ; a b a b
  popip

jump-if-nonzero: ; ( dest_address predicate -- )
  swap jnz
  popip

; The start of our Fibonacci printing program

main:
  count-init

  0 show  ; first Fibonacci number
  1       ; second Fibonacci number

  loop:
    ; add top numbers and show
    ; a b -> a b a b -> a b (a + b)
    dup2 add show

    ; decrement, loop if non-zero
    count-dec &loop jump-if-nonzero

I've added a HALT instruction. This replaces the old idiom of looping forever to signal that a program was finished:

stop: stop      ; form 1
stop: &stop jmp ; form 2
halt            ; convenience form

Originally, it was an argument of minimalism for not including any halt instructions.

Secondly, I've added a POPIP instruction along with automatically storing the next instruction before performing a jump. This effectively let's you call and return from subroutines:

boot:
  &main jmp halt

foo: bar: baz:
  '\n' '!' 'e' 'c' 'i' 'u' 'j' 'e' 'l' 't' 'e' 'e' 'B'
  out out out out out out out out out out out out out
  popip

main:
  foo bar baz

Third, I never bothered to write my own print number function, because it would require me to write both division and modulus functions in source first. So I implemented OUTNUM that prints a number to the output:

123 OUTNUM '\n' OUT ; prints "123\n"

Lacking is proper string handling. One could say that string handling is not this language's strongest point.

To compile and run the examples:

$ make all check

To see the low-level machine instructions:

$ ./smr -h

To execute source code on-the-fly:

$ ./sm filename

To compile source to bytecode:

$ ./smc filename

The assembly language is not documented other than in code, because I'm actively playing with it.

Although the interpreter is slow, it should be possible to convert stack operations to a register machine. In fact, it should be trivial to compile programs to native machine code, e.g. x86.

The instructions are found include/instructions.hpp:

VALUE       OPCODE  EXPLANATION
0x00000000  NOP     do nothing
0x00000001  ADD     pop a, pop b, push a + b
0x00000002  SUB     pop a, pop b, push a - b
0x00000003  AND     pop a, pop b, push a & b
0x00000004  OR      pop a, pop b, push a | b
0x00000005  XOR     pop a, pop b, push a ^ b
0x00000006  NOT     pop a, push !a
0x00000007  IN      read one byte from stdin, push as word on stack
0x00000008  OUT     pop one word and write to stream as one byte
0x00000009  LOAD    pop a, push word read from address a
0x0000000A  STOR    pop a, pop b, write b to address a
0x0000000B  JMP     pop a, goto a
0x0000000C  JZ      pop a, pop b, if a == 0 goto b
0x0000000D  PUSH    push next word
0x0000000E  DUP     duplicate word on stack
0x0000000F  SWAP    swap top two words on stack
0x00000010  ROL3    rotate top three words on stack once left, (a b c) -> (b c a)
0x00000011  OUTNUM  pop one word and write to stream as number
0x00000012  JNZ     pop a, pop b, if a != 0 goto b
0x00000013  DROP    remove top of stack
0x00000014  PUSHIP  push a in IP stack
0x00000015  POPIP   pop IP stack to current IP, effectively performing a jump
0x00000016  DROPIP  pop IP, but do not jump
0x00000017  COMPL   pop a, push the complement of a

The instruction set could easily be more minimal, even more so if we allowed registers. Also, we have taken absolutely no care about the machine code values for each instruction. A good design would do something cool with that.

Placed in the public domain in 2010 by the author, Christian Stigen Larsen http://csl.sublevel3.org