golem's vm early draft

1 files changed, 40 insertions, 0 deletions

diff --git a/vm.md b/vm.md
new file mode 100644
index 0000000..8cde69d
--- /dev/null
+++ b/vm.md
@@ -0,0 +1,40 @@
+# GOLEM's VM
+
+GOLEM should compile to *something*, and bytecode seems to be the most
+appropriate for various reasons, including portability and longevity.
+
+This VM (and GOLEM in general) won't be optimisation beasts, but they will be
+functionnal and if a need to make a large GOLEM program faster comes up in the
+future it will be certainly doable by writing a custom compiler. Consider this
+to be a reference implementation.
+
+## gyte size
+
+GOLEM bytes will be called gytes to avoid any confusion. Bytes in this document
+will refer to 8 bits.
+
+Gyte size could be program specific or fixed.
+
+## header
+
+1 byte will contain gyte size.
+
+1 gyte will contain static data size.
+
+Static data will be stored in the header and will be loaded at the start of the
+VM memory.
+
+## memory
+
+GOLEM needs two memory regions:
+* the stack for small volatile data
+* the heap for allocated, large or long lasting data
+
+Memory sizes should be specified to the VM.
+
+## VM stacks
+
+GOLEM will have two stacks (to not counfound with memory stack):
+* the instruction stack to be used by instructions and immediate operations
+* the return stack used to store the program counter on function call and
+restore it on return