{%hackmd -4u56Mp1SxmlnQGy5kgFWg %}
<!--
DAS'S REGULAR OL ASSEMBLY THING CORNER

# bytecode layout
bytecode will consist of 2 sections, metadata and code
metadata will contain various values and tables such as max call stack depth
example instead of explaining:

this

VAR pp u64 = 1;
VAR p u64 = 1;
VAR c u64 = 0;

:label
    c = p + pp;
    pp = p;
    p = c;
    PUT c;
    GOTO label;

HLT

compiles into:

<offsets>
.maxCallstackDepth 0
.maxStackDepth 1
.jumptargets
0 L0
.control
"adjacency_count_edges" 1 0x01
.variables
0 u64 1 GLOB "pp"
1 u64 1 GLOB "p"
2 u64 0 GLOB "c"
.code
L0: PUSHV 0
L1: PUSHV 1
L2: ADD
L3: POPV 2
L4: PUSHV 1
L5: POPV 0
L6: PUSHV 2
L7: POPV 1
L8: PUSHV 2
L9: PUT //some debug thing to print shit to stdout of the interpreter
L10: JMP 0 //as in jump table index 0

ADD etc. could type check stuff on the stack if the operation could be done
for ex if i push an i8 and a string, ADD would halt
the Ln stuff wouldnt exist when compiled to machine code or whatever
oh and L1 wouldnt need to come after L0 in an actual compilation since a single instruction can be multiple bytes
L sounds like line but i meant it as just an offset to .code
L0 == .code + 0x00
L69 == .code + 69
-->

# language
## Keywords
<!-- Note about keyword stuff:
[ stuff ] = optional
stuff = required
? at end means considering
-->
Shared:

CSET compiler_var, value
ISET interpreter_var, value
VAR name, type [= value]
SLEEP [time ms]
GOTO label [IF expression [ELSE label]]
:label
//comment
LOOP range:
ENDL

<!-- ## Thonk corner:
:label
<some map shit idk>
GOTO ::nested_label_end ;equivelant to `GOTO label :label.nested_label
::nested_label //new syntax, nested labels. nested_label here would mean label.nested_label
<some other map shit idk>
RET;
::nested_label_end
<some other shit>
CALL :label.nested_label ;;or ::nested_label
RET;

dis fine?

call stack times

no return valus so i wont bother with planning a frame thing

Interpreter mode call stack could be up to the interpreter
implementer to define but a sensible thing would be to
store the bytecode index as return values.

Compiled call stack would be target dependent where you'd store addresses to return to

**through** CALL and RET definition:
CALL label [IF condition [ELSE label]];
behaviour:
store where the instruction is executed in the call stack, rest of the behaviour is the same as GOTO where you jump to the label

RET;
behaviour:
pop the top value from the call stack, incerment the value to point to the instruction/line/whatever that comes after the instruction
if the targeted location is out of bounds, just quit
GOTO the target location
if stack underflow while popping:
do a state dump and quit

meta instructions to implement this maybe:
CPUSH offset; -> push the current location + offset

conversions to implement this:
`CALL label IF condition ELSE label` turns into:
CPUSH 2;
GOTO $label IF $condition ELSE $label

`RET` is ret

some nested label stuff:

:label

^ valid, surface level label

::label

^ this is invalid, no parent to label which is a layer deep

:label0
::label1

^valid, ::label1 expands to :label0.label1 (during preprocessing) and any references of ::label1 inside the surface level label `label0` expand to `:label0.label1`

:label0  //current surface level label is now label0
::label2 //:label0.label2
:label1  //now it is set from label0to label1
::label2 //:label1.label2

-->

<!--
somewhat simpler, not-self-contained explanation:

CALL and RET respectively pushes the next instruction to execute after call and pops the stored instruction from the callstack. with conditions obv.

preprocessor does stuff to expand the following example

:label_foo
::label_bar
:label_baz
::label_bar

into:

:label_foo
:label_foo.label_bar
:label_baz
:label_baz.label_bar

-->

Wallmap gen:
<!-- Wallmap gen keywords should only be related to generating the map -->

CLEAR [store]
FILL [store] [AT random/edges] [IN range/store] [IF expression]
CELL rules [AT random/edges] [IN range/store] [TO store] [IF expression]
LOAD store [TO store]
INVERT [store]
MASK [store] WITH store USING operator
PRESET num USING store [IN range/store] [IF expression]
SPRINT [store]
NOISE type[, options as defined by type] [IN range/store] ?
FILTER type[, options as defined by type] ?

Protomap gen:

PLACE file [AT random/edges] [IN range] [IF expression]
ADD object [AT random/edges] [IN range] [IF expression]

## Opcodes:
<!-- 
Because there are different instructions for different phases of the map generation process there are certain reserved ranges for instructions.
Every range with the exception of Reserved/Free must be standard across all interpreters and compilers, this just means you can't add a new instruction to the ranges unless it is added to this doc also some versioning shit idk.
0x00 to 0x64 - General instructions not related to map generation
0x65 to 0xA3 - Wallmap generation instructions.
0xA4 to 0xC7 - Protomap generation instructions.
0xC8 to 0xF9 - Reserved/Free
0xFA to 0xFF - Debug
-->
#### 0x00 - NOOP
NO OPeration

#### 0x01 - SLEP
SLEeP

#### 0x02 - ISET
Interpreter SET

#### 0x03 - VSET
Variable SET

#### 0x04
TODO

<!-- Wallmap opcodes begin here --->
#### 0x65


<!-- Protomap opcodes begin here --->
#### 0xA4

<!-- Reserved/free opcodes begin here --->
#### 0xC8 to 0xF9
Reserved

<!-- Debug opcodes begin here --->
#### 0xFF - SDMP
State DuMP

Das' VM plans which pretty much completely ignores tceo's stuffs above

Basic file layout for an executable archive/folder:
SYML
SYMS (optional, for debugging purposes)
OBJ0
OBJ1
...
(up to 65536 OBJ files)

SYML: Symbol lookup
this file contains an indexed list of pairs which contain in which file a symbol exists and at what (byte) offset.
there can be up to 2^32 entries, first 2^16 of which are reserved for frequently accessed symbols.
Example layout:
0 0 0 (entry for some symbol in object file 0 and offset 0)
1 0xDEAD 0xBEEF (entry for some symbol in object file 0xDEAD and offset 0xBEEF)

SYMS: Symbol to string lookup
this file contains string represntation of symbols (symbols are indicated by SYML indices). it is only for the use of a debugger and a program wont be able to use it.
Example layout:
0 "main"
1 "fooFunction"

OBJ files:
these contain the bytecode of the program in single or multiple object files.

How the VM works:
This VM is a stack machine which is mostly weakly typed. IDK how objects (as in user defined types) will work but im sure ill figure shit out later on
<Insert Java like registers here later on, currently this is forth like>

Opcodes take 4 bytes and the instruction's length is dependant on the opcode.

Primary operations are: stack operations (pushes and manipulations), loads, stores (from and to registered values/objects), arithmetic operations (only for primitive types), jumps (x86 like, weakly typed(explained later), comparison beforehand), and calls

Notes:
Weak typing:
consider we push an I8 and a F32 to the stack and execute ADD. the VM
will take both numbers and widen/narrow the values after the first to
match the size of the first. Data might be lost during this if the
action is narrowing.
TO-DECIDE: do we narrow or widen when there's a size mismatch? or just throw a runtime error or sth if there's a mismatch and expect the programmer/compiler to cast to necessary types (would add another instruction like PCAST (primitive cast): `PCAST F32 I64`)
Symbols:
symbols are just some word for labels. the symbols get resolved by
the vm to their approparite locations in sapecific object files and
offsets during runtime using the SYML file. The first 65536 symbols
are used to store the symbols that get accessed the most (in terms of
raw amount, not runtime amount) in executables that have more than
65536 symbols.
Types:
the planned types are:
(I|U)(8|16|32|64)
F(16|32|64|80|128|256)
vector instructions can be applied to F64 and above floating points
some type for objects will be implemented (`void *` maybe?)
The `void *` remark from above:
There could be a class lookup table and an object could be pushed as
a void * which then gets cast to a class for future invocations(?)

NEW (class index)
INVOKEAS (class index) (function)

or an `Object` type could do those things on the background which
limits the freedom in polymorphism (which isn't necessarily bad)

@TCEO write shit here in criticism of my dumb ideas and improve it
uhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh, seems fine?