Instruction Set - craterdog-archives/js-bali-virtual-machine GitHub Wiki

Musings

Soldier

"Eight kinds of soldier marching in a line, when they work together everything's devine." —the craterdog

The Instruction Set

The Bali Virtual Machine™ was designed to be as simple as possible while still providing powerful instructions that integrate seamlessly with modern cloud architectures. It supports an instruction set consisting of only eight instructions, each with four possible modifiers and an optional operand.

The bytecode for each instruction is two bytes (16 bits) long with the bits interpreted as follows:

  | opcode (3 bits) | modifier (2 bits) | operand (11 bits) |

The opcode is in the range 0..7 and defines which instruction is to be executed:

  • JUMP (un)conditionally to a new instruction address.
  • PUSH onto the top of the stack a component from the local context.
  • PULL the component on the top of the stack to be used by the local context.
  • LOAD onto the top of the stack a document from the cloud environment.
  • SAVE the document on the top of the stack into the cloud environment.
  • DROP a component from the cloud environment.
  • CALL an intrinsic function with optional arguments.
  • SEND a message with optional arguments to a local component or cloud-based document.

The modifier for each instruction is in the range 0..3 and has different meanings for each instruction type. Click on the name of each instruction above to see detailed documentation and examples for them.

The operand represents one of the following:

  • unused with a value of 0
  • an index in the range 1..2047 (unit based indexing)
  • an address in the range 0x001..0x7FF (unit based addressing)

To get a feel for the bytecode encodings for each possible modifier for each instruction we can print out an example listing that contains one of each combination of instruction and modifier:

 Addr     Bytes   Bytecode                 Instruction
-------------------------------------------------------------------
[001]:    0000    00 [000]    JUMP TO NEXT INSTRUCTION
[002]:    0001    00 [001]    JUMP TO [001]
[003]:    0802    01 [002]    JUMP TO [002] ON EMPTY
[004]:    1003    02 [003]    JUMP TO [003] ON NONE
[005]:    1804    03 [004]    JUMP TO [004] ON FALSE
[006]:    2005    10 [005]    PUSH HANDLER [005]
[007]:    2806    11    6     PUSH LITERAL 6
[008]:    3007    12    7     PUSH CONSTANT 7
[009]:    3808    13    8     PUSH ARGUMENT 8
[00A]:    4000    20    0     PULL HANDLER
[00B]:    4800    21    0     PULL COMPONENT
[00C]:    5000    22    0     PULL RESULT
[00D]:    5800    23    0     PULL EXCEPTION
[00E]:    600D    30   13     LOAD VARIABLE 13
[00F]:    680E    31   14     LOAD DOCUMENT 14
[010]:    700F    32   15     LOAD CONTRACT 15
[011]:    7810    33   16     LOAD MESSAGE 16
[012]:    8011    40   17     SAVE VARIABLE 17
[013]:    8812    41   18     SAVE DOCUMENT 18
[014]:    9013    42   19     SAVE CONTRACT 19
[015]:    9814    43   20     SAVE MESSAGE 20
[016]:    A015    50   21     DROP VARIABLE 21
[017]:    A816    51   22     DROP DOCUMENT 22
[018]:    B017    52   23     DROP CONTRACT 23
[019]:    B818    53   24     DROP MESSAGE 24
[01A]:    C019    60   25     CALL 25
[01B]:    C81A    61   26     CALL 26 WITH 1 ARGUMENT
[01C]:    D01B    62   27     CALL 27 WITH 2 ARGUMENTS
[01D]:    D81C    63   28     CALL 28 WITH 3 ARGUMENTS
[01E]:    E01D    70   29     SEND 29 TO COMPONENT
[01F]:    E81E    71   30     SEND 30 TO COMPONENT WITH ARGUMENTS
[020]:    F01F    72   31     SEND 31 TO DOCUMENT
[021]:    F820    73   32     SEND 32 TO DOCUMENT WITH ARGUMENTS