Virtual machine

Notation for 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

Notation of stack diagrams for instructions and functions

 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 ;

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.

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

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 code instructions Version 2

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           - 32 bit two's complement addition
           1 SUB
           2 MUL
           3 DIV           - 32 bit unsigned division
           4 SDIV
           5 LSL
           6 LSR
           7 ASR
           8 ROR
           9 AND
           A OR
           B EOR
           C NOT
           D NEG
           E INC
           F DEC      
   E OPR3 #imm4
           0 DUP
           1 DROP
           2 SWAP
           3 OVER
           4 ROT
           5 -ROT
           6 R
           7 >R
           8 @R / COPYR
           9 LD32
           A ST32
           B LD16
           C ST16
           D LD8
           E ST8
           F NOP
   F OPR4 #imm4
           0 FOR
           1 NEXT
           2 DO
           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 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