NOTATION

Given a stack effect ( a^ b^ c^ -- c^ a^ b^ ) here is what each symbol means:

( and ) are comment delimiters
a^, b^, and c^ are values on the stack
^ indicates that each value is a byte (* would indicate short)
-- separates the "before" and "after" of the stack effect

The effect here is to move the top byte of the stack below the next two bytes, which could be achieved with ROT ROT.

By default stack effects describe the effect on wst. When rst is involved we use [] to differentiate the stacks. For example ( a* [b*] -- a+1* [b+1*] ) will increment the top short of both wst and rst.

EFFECTS AND MODES

Regular instructions have a single stack effect which is modified in a predictable way by any additional modes.

For example the generic effect for ADD is ( x y -- x+y ). The eight combinations of modes have the following effects:

    ADD    ( x^ y^   -- x+y^ )         sum bytes from wst


    ADDr   ( [x^ y^] -- [x+y^] )       sum bytes from rst


    ADD2   ( x* y*   -- x+y* )         sum shorts from wst


    ADD2r  ( [x* y*] -- [x+y*] )       sum shorts from rst


    ADDk   ( x^ y^   -- x^ y^ x+y^ )   sum and keep bytes from wst


    ADDkr  ( [x^ y^] -- [x^ y^ x+y^] ) sum and keep bytes from rst


    ADD2k  ( x* y*   -- x* y* x+y* )   sum and keep shorts from wst


    ADD2kr ( [x* y*] -- [x* y* x+y*] ) sum and keep shorts from rst

Thus for regular instructions writing a "generic" effect (leaving sigils off values whose size depends on short mode) is sufficient to describe its behavior across all eight variations. Note that some instructions always read values of a fixed size. For example the boolean condition read by JCN is always one byte, no matter what modes are used.

In return mode the stacks are reversed. Effects on wst will instead affect rst, and effects on rst will instead affect wst. For example, STH reads a byte from wst and writes it to rst, but STHr reads a byte from rst and writes it to wst.

In keep mode all the values on the left-hand side of the stack effect will also appear on the right-hand side before the outputs. For example, SWP is (x y -- y x) but SWPk is (x y -- x y y x).

TERMINOLOGY

We consider the top of the stack to be the first value of the stack, and count back from there. For example, given the stack effect ( a b c -- ) we would say that c is the top of the stack, b is the second value (second from the top), and a is the third value (third from the top).

INC ( x -- x+1 )

Increment the top value of the stack by 1.

Overflow will be truncated, so #ff INC will evaluate to 0x00.

POP ( x -- )

Remove the top value of the stack.

POPk is guaranteed to have no effect (it will not change the stack).

NIP ( x y -- y )

Remove the second value of the stack.

NIPk is guaranteed to have no effect (it will not change the stack).

SWP ( x y -- y x )

Swap the top two values of the stack.

ROT ( x y z -- y z x )

Rotate the top three values of the stack. The lowest becomes the top and the others are each shifted down one place.

DUP ( x -- x x )

Place a copy of the top value of the stack on top of the stack.

OVR ( x y -- x y x )

Place a copy of the second value of the stack on top of the stack.

EQU ( x y -- x==y^ )

Test whether the top two values of the stack are equal.

Result is guaranteed to be boolean (0x00 or 0x01).

NEQ ( x y -- x!=y^ )

Test whether the top two values of the stack are not equal.

Result is guaranteed to be boolean (0x00 or 0x01).

GTH ( x y -- x>y^ )

Test whether the second value of the stack is greater than the top.

Result is guaranteed to be boolean (0x00 or 0x01).

LTH ( x y -- x<y^ )

Test whether the second value of the stack is less than the top.

Result is guaranteed to be boolean (0x00 or 0x01).

JMP ( x -- ; pc <- x )

Jump to a location.

The program counter (pc) is unconditionally updated. When x is a byte, it is treated as relative (pc += x) and when x is a short it is treated as absolute (pc = x).

It is common to JMP with boolean bytes (0-1) to handle simple conditionals. For example:

@max ( x^ y^ -- max^ ) GTHk JMP SWP POP JMP2r

JCN ( bool^ x -- ; pc <- x if bool )

Jump to a location when a condition is true.

The program counter (pc) is updated when bool is non-zero. When x is a byte, it is treated as relative (pc += x) and when x is a short it is treated as absolute (pc = x).

JSR ( x -- [pc+1*] )

Jump to a location, saving a reference to return to.

Stores the next address to execute before unconditionally updating the program counter (pc). This instruction is usually used to invoke subroutines, which use the JMP2r to return. When x is a byte, it is treated as relative (pc += x) and when x is a short it is treated as absolute (pc = x).

The saved address will always be a short regardless of short mode.

STH ( x -- [x] )

Move the top value of the stack to the return stack.

LDZ ( zp^ -- x )

Load data from a zero-page address (0x00 - 0xff).

STZ ( x zp^ -- )

Store data at a zero-page address (0x00 - 0xff).

LDR ( rel^ -- x )

Load data from a relative address (pc + x).

Note that unlike LDZk and LDAk the LDRk instruction is not very useful, since a relative address is usually only meaningful when run from a particular address (i.e. for a particular pc value).

STR ( x rel^ -- )

Store data at a relative address (pc + x).

Note that unlike STZk and STAk the STRk instruction is not very useful, since a relative address is usually only meaningful when run from a particular address (i.e. for a particular pc value).

LDA ( abs* -- x )

Load data from an absolute address (0x0000 - 0xffff).

STA ( x abs* -- )

Store data at an absolute address (0x0000 - 0xffff).

DEI ( dev^ -- x )

Read data from a device port (0x00 - 0xff).

Reading from some ports may have an effect on the underlying VM; in other cases it will simply read values from device memory. See Varvara device documentation for more details.

DEO ( x dev^ -- )

Write data to a device port (0x00 - 0xff).

Writing to some ports may have an effect on the underlying VM; in other cases it will simply write values to device memory. See Varvara device documentation for more details.

ADD ( x y -- x+y )

Add the top two values of the stack.

Overflow will be truncated, so #ff #03 ADD will evaluate to 0x02.

SUB ( x y -- x-y )

Subtract the top of the stack from the second value of the stack.

Underflow will be truncated, so #01 #03 SUB will evaluate to 0xfe.

MUL ( x y -- xy )

Multiply the top two values of the stack.

Overflow will be truncated, so #11 #11 MUL will evaluate to 0x21.

DIV ( x y -- x/y )

Divide the second value of the stack by the top of the stack.

DIV implements Euclidean division, which is also known as integer division. It returns whole numbers, so #08 #09 DIV evaluates to 0x00.

Division by zero will return zero (instead of signaling an error).

Unlike ADD, SUB, and MUL, DIV does not behave correctly for numbers which should be treated as signed. For example, the signed byte representation of -2 is 0xfe, but #06 #fe DIV evaluates to 0x00 (6 / 254 = 0). For signed values the correct result should instead be 0xfd (6 / -2 = -3).

There is no remainder instruction, but the phrase DIVk MUL SUB can be used to compute the remainder.

AND ( x y -- x&y )

Compute the bitwise union of the top two values of the stack.

ORA ( x y -- x|y )

Compute the bitwise intersection of the top two values of the stack.

EOR ( x y -- x^y )

Compute the bitwise exclusive-or (xor) of the top two values of the stack.

SFT ( x rl^ -- (x>>l)<<r )

Compute a bit shift of the second value of the stack; the directions and distances are determined by the top value of the stack.

Given a byte rl consisting of a low nibble (l) and a high nibble (r), this instruction shifts x left by l and then right by r.

Right shifts are unsigned (they introduce zero bits). There are no signed shifts.

For 16-bit (and 8-bit) values, one nibble (0x0 - 0xf) is sufficient to express all useful left or right shifts.

Right: #ff #03 SFT evaluates to 0x1f
Left: #ff #20 SFT evaluates to 0xfc
Both: #ff #23 SFT evaluates to 0x7c

BRK

The break instruction is used to end a vector call and return control to the virtual machine.

JCI, JMI, and JSI

The "immediate jump" instructions are produced by the assembler. They interpret the next 2 bytes of the ROM as a relative address (addr) and have the following effects:

JMI ( -- ) jump to addr unconditionally
JCI ( bool^ -- ) jump to addr if bool is non-zero
JSI ( -- [pc*] ) jump to addr saving the current address (pc) on rst

(The instruction pointer will be moved forward 2 bytes, past the relative address.)

These instructions are created by the assembler from special syntax:

!dest produces JMI wx yz
?dest produces JCI wx yz
dest produces JSI wx yz (assuming dest is not a macro or reserved)

LIT, LIT2, LITr, and LIT2r

Push a literal value on the stack.

The "literal" instructions are used to push new data onto the stacks. They interpret the next 1-2 bytes of the ROM (wx, wxyz) as data and push it onto the corresponding stack:

LIT ( -- wx^ ) push literal byte wx onto the wst
LITr ( -- [wx^] ) push literal byte wx onto the rst
LIT2 ( -- wxyz* ) push literal short wxyz (2 bytes) onto the wst
LIT2r ( -- [wxyz*] ) push literal short wxyz (2 bytes) onto the rst

(The instruction pointer will be moved forward 1-2 bytes, past the literal data.)

Literal values can be updated dynamically using store instructions:

#abcd ;x STA2
( later on... )
LIT2 [ @x $2 ]