release 0.0.2

Author: zenMaya

.gitignore

@@ -1,2 +1,3 @@
 zig-cache
-zig-out
+zig-out
+.vscode

README.md

@@ -4,7 +4,7 @@
 
 # What is AgarVM?
 
-Agar is a virtual machine. It comes with an assembly language.
+Agar is a register virtual machine. It comes with an assembly language.
 
 You can test agar by writting assembly and running
 

docs/developer/asm.md

@@ -0,0 +1,13 @@
+# Assembler (asm.zig)
+
+This file contains a struct that allows parsing strings into Agar bytecode. Label resolution is currently limited and only works with labels that are defined before the label usage. This will be fixed in the future.
+
+Assembler uses a fairly standard patter with one exception. There is an additional step, you initialize it, then run the `.assembly_pass()` which creates the `instruction_buffer` which you can then copy elsewhere and finally deinitialize it.
+
+The reason for the assembly pass step is that it is possible in the future to add more steps to the compilation.
+
+The `.tokenize_*()` functions convert the strings into tokens, based on lines and spaces. There are no commas or anything like that, syntactic meaning is handled using just spaces and line breaks inside the assembly.
+
+The `.parse_line()` function scraps lines beginning with `;`, if the first token ends with `:` then registers a label and otherwise tries to parse the line as a instruction. If the instruction is a pseudoinstruction then it is first expanded into a slice of instructions.
+
+The `.label_to_offset()` function takes a label or a integer and converts it into a integer, if the label exists or is an integer. Any instruction can take an immediate in form of a label, they are mutually interchangeable.

docs/developer/binary.md

@@ -0,0 +1,9 @@
+# Binary (binary.zig)
+
+The original (and future) plan is to use the ELF binary format. But this turned out to be quite a complex task, so in the meantime Agar uses a very simple binary format. It has no checksum, but at least can check if the code has the correct version.
+
+| start | number of bytes | meaning                                                                 |
+| ----- | --------------- | ----------------------------------------------------------------------- |
+| 0     | 6               | the Agar magic number, it is the string "agarVM" in ASCII               |
+| 6     | 2               | Agar version, it is changed each time the binary format is incompatible |
+| 8     | X               | the Agar bytecode                                                       |

docs/developer/index.md

@@ -0,0 +1,12 @@
+# AgarVM architecture
+
+*Agar consists of several modules. Each will be documented here.*
+## Table of contents
+### The bytecode architecture
+- [Instructions](./instructions.md)
+- [Registers](./registers.md)
+### The code architecture
+- [Virtual Machine](./vm.md)
+  - [Page Manager](./page_manager.md)
+- [Assembler](./asm.md)
+- [Binary](./binary.md)

docs/developer/instructions.md

@@ -0,0 +1,25 @@
+# Instructions
+
+## Instruction format
+Instructions are modeled after the Risc-V architecture but with modifications. They are strictly 32 bits wide always saved in little endian.
+> Note that the format listed below is backwards from the real memory representation. The bit 0 is on the right and bit 31 is on the left. Same as we write numbers - MSB first.
+### the R-format for 3 operand instructions
+```
+|0|1|2            16|17 21|22 26|27 31|
+|0|0|xxxxxxxxxxxxxxx|xxxxx|xxxxx|xxxxx|
+|-|R|opcode         |rd   |rs1  |rs2  |
+```
+### the I-format for instructions with immediates
+```
+|0|1       9|10 14|15 19|20        31|
+|1|xxxxxxxxx|xxxxx|xxxxx|xxxxxxxxxxxx|
+|I|opcode   |rd   |rs1  |imm12       |
+```
+### the C-format for instructions with bigger immediates
+```
+|0|1|2   6|7  11|12                31|
+|0|1|xxxxx|xxxxx|xxxxxxxxxxxxxxxxxxxx|
+|-|C|opcod|rd   |imm20               |
+```
+## Binary compatibility
+Opcode numbers *can* be changed between versions. To prevent malfunctioning code each `.agar` file has version of the instruction set written and should produce an error instead of running other versions (as described in the `AGAR_VM_VERSION` variable) of code.

docs/developer/page_manager.md

@@ -0,0 +1,17 @@
+# Page Manager (page_manager.zig)
+
+Memory is in Agar managed in pages. Each page is addressed by the 12 bit immediate. The only difference is that address inside a page is always between 0 and 4095, so there is no reason to use signed immediates and thus the immediate is casted to unsigned integer and used that way.
+
+Page manager uses the zig feature of file structs. In reality it just means that the file itself is treated as a struct. If it hard to comprehend than imagine that you just wrap everything in the file inside `struct {}`.
+
+## Initialization
+
+The struct uses the usual zig `.init()` & `.deinit()` pattern.
+
+## Runtime
+
+There are only two functions in this struct. The one is for initializing new pages and the other is for releasing them. The pages are stored in a ArrayList and the id in which the struct identifies pages is the index in this array. There is no guarantee that the id is unique, usually pages are reused.
+
+The handling of freed pages is that if they appear on the end of the array, they are released if they are in the middle of the array, they are marked as free but not released from the memory. This is done simply because this can assure that the access and all functions will be O(1) as rearranging arrays is O(n).
+
+The free pages are stored into a singly linked list as it doesn't matter in which order they are reused and linked list allows for an easy O(1) LIFO queue.

docs/developer/registers.md

@@ -0,0 +1,12 @@
+# Registers
+| register identifier | description                      |
+|---------------------|----------------------------------|
+| zero                | register with the constant 0     |
+| ra                  | return address                   |
+| pp                  | page pointer                     |
+| t0-t6               | temporary registers              |
+| s0-s11              | saved registers                  |
+| a0-a9               | function arguments/return values |
+
+## The `zero` register
+Origin of this register is from the Risc-V architecture. Note that all registers are named only for user convenience. There is no guarantee that any register will have a value that it should have. **Not even the `zero` register!** You can assign a value to the `zero` register. But if you run any third-party code note that it can lead to undefined behavior.

docs/developer/vm.md

@@ -0,0 +1,40 @@
+# The Virtual Machine (vm.zig)
+
+This file comprises of the actual execution engine. It has 32 64bit registers (this is a limitation due to register ids can only be stored in 5 bits). All instructions are saved in 32 bits. It has a few advantages, as near jump instructions (all pc modifying I-type instructions) can actually address a 4095 other addresses (2047 back and 2046 front).
+
+All arithmetic is done on two's complement signed 64 bit integers if not stated otherwise.
+
+## Initialization
+
+The VM can be initialized in multiple ways. The standard way is to create a VM struct and then call the `.run()` function. It automatically initializes the virtual machine, and starts executing code.
+
+```zig
+var vm = VM{
+  .program = program[0..],
+};
+
+vm.run(event_allocator, page_allocator);
+
+// at the end of this scope, deinitialize all the virtual machine's memory.
+defer vm.deinit();
+```
+
+The `.run()` function takes two allocators. These are responsible for the memory allocation of particular type (usually you can pass both the same allocator). The `event_allocator` is for the virtual machine events. These are messages that you can use to signal to the VM or the VM itself can use to signal to you.
+
+The `page_allocator` is used to allocate memory inside the virtual machine, the `gp` and `fp` instructions use it to create and free pages. You should use a high performing allocator, it can be beneficial to use the `c_allocator` even though it can produce leaked memory and must be handled with caution.
+
+The couple `.init()` and `.deinit()` are used to initialize and deinitialize structs inside the VM itself. It is a standard zig pattern. All heap allocated memory is freed in `.deinit()`.
+
+## Runtime
+
+`.next_instruction()` this function is a simple one. It returns the next instruction at position of the program counter (`pc`) and advances it by one.
+
+`.exec_instruction()` this function executes one instruction on the VM. It can halt the VM or it should continue.
+
+| returned value | meaning                                                                                   |
+| -------------- | ----------------------------------------------------------------------------------------- |
+| `VMError.*`    | the VM encountered an error, you should handle it accordingly, the default is to halt     |
+| `false`        | the VM halted with the `HLT` instruction, the error code is written in the `VM.exit_code` |
+| `true`         | the VM should continue it's execution                                                     |
+
+There are some at first glance weird methods (starting with the `@` symbol) but that's just a type casting that is quite strict in zig and is very well defined contrary to C for example.