# The Instruction Set

This document describes the instruction set of Essentia.
It is not finished and is likely to change in the future.


## Abbreviations

This document uses a set of abbreviations to improve readability.

| abbr | description             |
| ---- | ----------------------- |
| u8   | 8-bit unsigned integer  |
| u16  | 16-bit unsigned integer |
| u32  | 32-bit unsigned integer |
| u64  | 64-bit unsigned integer |
| UB   | undefined behavior      |

## Instruction Encoding

Each instruction is specified by a single byte, data after it is instruction-specific.
The information below describes interpretation of this data for different instructions.

## Unconditional Branch Instructions

* 0x00 - JUMP
* 0x01 - CALL
* 0x02 - CALL_SYS

This instructions are self-explanatory, except the CALL instruction. When the
callee gains control, it is not aware about the caller's variables, thus they
must be hidden from it. It is done by the CALL instruction, which makes it look
like there were no variables before the callee. Specifically, the current
variable state array is preserved until the RETURN instruction is executed.
The CALL instruction also preserves CPU registers, according to
the target calling convention.


| offset | type | description                        |
| ------ | ---- | ---------------------------------- |
| 0x00   | u64  | destination variable index         |
| 0x08   | u64  | argument number                    |
| 0x10   | u64  | array of argument variable indexes |

## RETURN Instruction

* 0x03 - RETURN

| offset | type | description                |
| ------ | ---- | -------------------------- |
| 0x00   | u64  | return variable index      |

## MOV Instruction

* 0x04 - MOV

| offset | type | description                |
| ------ | ---- | -------------------------- |
| 0x00   | u64  | destination variable index |
| 0x08   | u64  | source variable index      |

## VAR Instruction

* 0x05 - VAR

The VAR instruction loads a variable with a state at a specified index.
The index must be an index of an existing variable or the lowest unused index.
If it will be greater, UB is caused.

| offset | type | description                          |
| ------ | ---- | ------------------------------------ |
| 0x00   | u64  | destination variable index           |
| 0x08   | ...  | variable state (see Architecture.md) |

## Math Instructions

* 0x06 - ADD
* 0x07 - SUB
* 0x08 - MUL
* 0x09 - DIV

| offset | type | description                  |
| ------ | ---- | ---------------------------- |
| 0x00   | u64  | destination variable index   |
| 0x08   | u64  | first source variable index  |
| 0x10   | u64  | second source variable index |

## LABEL Instruction

* 0x0A - LABEL

This instruction leaves a label in the output assembly file.
Each label must have a corresponding entry in the symbol table.

| offset | type | description                  |
| ------ | ---- | ---------------------------- |
| 0x00   | u64  | symbol index                 |

## DAT Instruction

* 0x0B - DAT

This instruction allows adding raw data to output binaries.

| offset | type | description                  |
| ------ | ---- | ---------------------------- |
| 0x00   | u64  | size of raw data             |
| 0x08   | ...  | raw data                     |

## MEMCPY Instruction

* 0x0C - MEMCPY

| offset | type | description                        |
| ------ | ---- | ---------------------------------- |
| 0x00   | u64  | destination pointer variable index |
| 0x08   | u64  | source pointer variable index      |
| 0x10   | u64  | transfer size variable index       |

## Math Instructions (signed)

* 0x0D - IMUL
* 0x0E - IDIV

## Math Instructions (floating point)

* 0x0F - FMUL
* 0x10 - FDIV

## Conditional Branch Instructions

* 0x11 - JE  - if equal
* 0x12 - JNE - if not equal
* 0x13 - JM  - if more
* 0x14 - JMS - if more signed
* 0x15 - JL  - if less
* 0x16 - JLS - if less signed

These instructions compare the source variables and load a new instruction pointer
if the condition is satisfied.

| offset | type | description                  |
| ------ | ---- | ---------------------------- |
| 0x00   | u64  | destination variable index   |
| 0x08   | u64  | first source variable index  |
| 0x10   | u64  | second source variable index |