# Architecture

This document is an overview of the whole architecture of Essentia.


## 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 |

## Compilation Stages

### Source -> Bytecode

A compiler translates its language into the Essentia intermediate bytecode.

### Bytecode -> Assembly

The Essentia bytecode compiler translates the bytecode into the target assembly.

## Virtual Machine

The instructions, encoded by the bytecode, command an abstract virtual machine to
do different things, a usual machine does. To achieve portability a set of abstractions
is applied.

### Variables

Since different CPU architectures, have different register sets, the abstract virtual machine
uses an unlimited set of registers, that are called variables. A variable can be anything:
a CPU register, an entry on the stack or an arbitrary memory location.

#### Variable State

| offset | type | description   |
| ------ | ---- | ------------- |
| 0x00   | u8   | location type |
| 0x01   | u64  | location      |

There are several types of locations:

* 0x00 - register

The interpretation of the location field is machine-dependent.

* 0x01 - stack

If the stack grows downwards, an offset from the top of the stack, otherwise - from the bottom.

* 0x02 - memory

A location of some data in memory.

* 0x03 - immediate

An immediate value, loaded from the location field directly.

* 0x04 - symbol

The location field is interpreted as an index in the symbol table.

* 0x05 - any

This is used for allocating new variables with the VAR instruction (see Instruction Set.md).

* 0x06 - argument

This is used with the VAR instruction for reading arguments passed to the current procedure.

All variables are 8-bit by default. To make one 16-bit, 32-bit or 64-bit the
location field must be OR'd with one of the following values:

* 0x20 - 16-bit
* 0x40 - 32-bit
* 0x80 - 64-bit

There is no difference between signed and unsigned variables on the state level.