Virtual machine

Functions

 :  Define a new function
 ;  End definition
 (  Start comment
 )  End comment

 Example, a function called inc that increases a value by 1
   : inc 1 add ;

 Write numbers directly without using LDC/LDN/LDE since they are implied
 After being defined a function can be used just like any other instruction

Stack diagrams

 A stack diagram shows how many items a function/instruction take from the stack and put back
 Show what is taken off the stack then what is put back on the stack separated by --
 n n -- n

 Example, a function called mul that takes two numbers off the stack and writes one number back
   : mul ( n n -- n ) 0 rot for over add next nip ;

 Use n for general numbers but name the items if it makes sense
 For example a function that calculates power from voltage and current
   : power ( volt ampere -- watt ) mul ;

Stacks

The virtual machine has two stacks, one for data and one for return addresses and variables. When writing down the stack on one line, the top of the stack is to the right on the line.

A stack with four items, 7 is the topmost item.
 1 4 2 7 

Performing an ADD instruction will result in this stack:
 1 4 9

2 and 7 are discarded and the sum 9 is written back to the stack.

Registers

The registers and stack cells are 32 bit each, the registers are internal to the virtual machine The registers will be put on the return stach when a function is called so the machine can return safely

Registers

 PC Program counter        - Points to the next instruction
 DP Data stack pointer     - Points to the next free cell on the data stack
 RP Return stack pointer   - Points to the next free cell on the return stack
 LP Local variable pointer - Points to the first local variable or local array element on the return stack
                             This is also used when unwinding a stack frame

Machine instructions

Each instruction is one byte (8 bits). The 4 most significant bits is the type of instruction and the 4 least significant bits is the data.

 7      0
 ttttdddd

When viewed in hexadecimal the first digit is the type and the second is the data. So the byte 0xDA is the OR instruction

Type     Data
   0 LDC #imm4             - Load 4 bit immediate constant
   1 LDN #imm4             - Load 4 bit immediate negative constant
   2 LDE #imm4             - Load extend as TOP = TOP:imm4
   3 LSL #imm4             - Logical shift left by n + 1
   4 DIM #imm4             - Reserve n + 1 elements on the return stack
   5 LDL #imm4             - Load local variable from the return stack
   6 STL #imm4             - Store local variable on the return stack
   7 SYS #'aaaa'           - Call system function as TOP:imm4
   8 LEA #'aaaa'           - Load effective address as TOP:imm4
   9 JUMP #'aaaa'          - Jump as TOP:imm4
   A CALL #'aaaa'          - Call function as TOP:imm4
   B OPR0 *RESERVED*       - Reserved for future expansion
   C OPR1 #imm4
           0 ADD.          - 32 bit IEEE 754 floating-point operation
           1 SUB.
           2 MUL.
           3 DIV.
           4 SQRT.
           5 TOF.          - Convert from integer to floating-point
           6 TOI.          - Convert from floating-point to integer 
           7 *RESERVED*    - Reserved for future expansion of floating-point
           8 *RESERVED*   
           9 *RESERVED*   
           A *RESERVED*   
           B *RESERVED*   
           C *RESERVED*   
           D *RESERVED*   
           E *RESERVED*   
           F *RESERVED*   
   D OPR2 #imm4
           0 ADD           - Addition                 ( n n -- n )
           1 SUB           - Subtraction              ( n n -- n )
           2 MUL           - Multiplication            
           3 DIV           - Unsigned division
           4 SDIV          - Signed division
           5 LSL           - Logical shift left
           6 LSR           - Logical shift right
           7 ASR           - Arithmetic shift right
           8 ROR           - Rotate right
           9 AND           - Bitwise AND
           A OR            - Bitwise OR
           B EOR           - Bitwise Exclusive OR
           C NOT           - Bitvise invert           ( n -- n )
           D NEG           - Negative                 ( n -- n )
           E INC           - Increase                 ( n -- n )
           F DEC           - Decrease                 ( n -- n )
   E OPR3 #imm4
           0 DUP           - Duplicate top of stack                ( a -- a a )
           1 DROP          - Drop top of stack                     ( a b -- a )
           2 SWAP          - Swap the two topmost items            ( a b -- b a )
           3 OVER          - Copy the second item                  ( a b -- a b a )
           4 ROT           - Rotate the top 3 items                ( a b c -- b c a )
           5 -ROT          - Rotate the top 3 items the other way  ( a b c -- c b a )
           6 R             - Move top of data stack to the return stack
           7 >R            - Move the top of the return stack to the data stack
           8 @R / COPYR    - Copy the top of the return stack to the data stack
           9 LD32          - Load a 32 bit value from memory ( address -- data )
           A ST32          - Store a 32 bit value to memory  ( data address -- )
           B LD16          - Load a 16 bit value from memory
           C ST16          - Store a 16 bit value to memory
           D LD8           - Load a 8 bit value from memory
           E ST8           - Store a 8 bit value to memory
           F NOP           - No-operation. ( -- )
   F OPR4 #imm4
           0 FOR    ( n -- ret )
           1 NEXT
           2 DO     ( -- ret )
           3 WHILE
           4 UNTIL
           5 AGAIN
           6 RP           - Return pointer
           7 >RP          
           8 FLAG
           9 NFLAG        - Not Flag, (if 0 else -1 endif)
           A IF
           B ELSE
           C ENDIF
           D JUMP
           E CALL
           F RETURN

Function call

Function call stack frame
          V0      V1      V2  <--  Local variables on the return stack accessed with the LDL and STL instructions
  PC LP <empty> <empty> <empty> ...
            \    
             \     
              The new LP points to the first local variable for the function
              RP points to the first free cell
  
  DIM #2 will cause the next two cells to be filled with 0, RETURN will delete any variables
          V0      V1      V2 
  PC LP    0       0    <empty> ...
            \               \                
             \               RP is advanced by two to the first free cell
              LP still points to the same position but the two first variables now contains 0