creature

A simple, extendable, 16 instruction stack machine.

It has two portions of memory: the stack and the block. I hesitate to call the block a heap because it is not a data structure, it is a continuous block of memory.

Both the stack and the block are infinite, to the extent computing resources and integer limits allow, in the positive direction. They are automatically expanded when written to.

Instruction Set

Each documented instruction has a list of what is pushed, and what is popped. the items are listed in chronological order, from first pushed/popped to last pushed/popped.

You'll notice that words specifying an address are always at the top of the stack. This helps increse security and reduce the likelihood of bugs. When writing functions to extend creature, it is highly advised that you follow this principle when deciding on an order to pop arguments off of the stack in.

0x0 PUSH

Pushes the next word in program memory onto the stack.

Pushes:

1. next word in program memory

0x1 POP

Pops the top word off of the stack, and discards it.

Pops:

1. word

0x2 PEEK

Reads a memory address from the block and places it atop the stack.

Pops:

1. address

Pushes:

1. word found at address

0x3 POKE

Sets a memory address in the block.

Pops:

1. address
2. value to store

0x4 ADD

Adds two words. Tip: this can be used as a logical OR.

Pops:

1. right operand
2. left operand

Pushes:

1. left operand + right operand

0x5 SUB

Subtracts two words.

Pops:

1. right operand
2. left operand

Pushes:

1. left operand - right operand

0x6 MUL

Multiplies two words.

Pops:

1. right operand
2. left operand

Pushes:

1. left operand * right operand

0x7 DIV

Divides two words.

Pops:

1. right operand
2. left operand

Pushes:

1. left operand / right operand

0x8 EQ

Checks if two words are equal. Pushes 1 if true, zero if false.

Pops:

1. right operand
2. left operand

Pushes:

1. left operand == right operand

0x9 GT

Checks if a word is greater than another word. Pushes 1 if true, zero if false.

Pops:

1. right operand
2. left operand

Pushes:

1. left operand > right operand

0xA LT

Checks if a word is less than another word. Pushes 1 if true, zero if false.

Pops:

1. right operand
2. left operand

Pushes:

1. left operand < right operand

0xB NEQ

Checks if two words are not equal. Pushes 1 if true, zero if false.

Pops:

1. right operand
2. left operand

Pushes:

1. left operand != right operand

0xC MOD

Performs a modulo operation on two words. Tip: this can be used as a logical AND.

Pops:

1. right operand
2. left operand

Pushes:

1. left operand % right operand

0xD HALT

Halts execution of the machine.

0xE JMP

Jumps to the specified address if a word is non-zero.

Pops:

1. address
2. condition

0xF CAL

Call a function that can be registered using the Machine.Register method. Functions are allowed to push and pop whatever they want to and from the stack, as well as read and write to and from the block.

Pops:

1. function ID
2. ...other stuff, it depends on the function.

Pushes:

1. ...again, depends on the function.