From 8be90132c80bf60c6047866d9517b4e98f3a2751 Mon Sep 17 00:00:00 2001
From: Mistivia <i@mistivia.com>
Date: Sun, 8 Dec 2024 22:12:40 +0800
Subject: add docs

---
 README.md | 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 111 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index fa00fd5..671c05d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,113 @@
 # Fantasy Virtual Machine
 
-A 64-bit stack-based virtual machine and its assembler, created for fun. The design principles are simplicity, clarity, portability, and ease of understanding. Future plans include programming language-related experiments based on this as foundation.
+A 64-bit stack-based virtual machine and its assembler, created for fun.
+
+## Build
+
+FVM includes two parts: the virtual machine and the assembler.
+
+The build the assembler, you need to intall CHICKEN Scheme first. For example, on Arch Linux:
+
+    sudo pacman -S chicken
+
+Then install CHICKEN Scheme dependencies:
+
+    sudo chicken-install matchable srfi-69 srfi-4
+
+Then run make, which will build both components:
+
+    make
+
+If successful, you will see two executables, the virtual machine `fvm` and the assembler`fvm-as`.
+
+## Run
+
+After writing the assembly code (examples can be found in the `examples` directory), first run the assembler:
+
+    ./fvm-as input.asm bytecode.bin
+
+This will generate the bytecode file `output.bin`. Then run the virtual machine:
+
+    ./fvm bytecode.bin
+
+## Registers
+
+FVM contains 4 registers:
+
+- SP: stack pointer
+- BP：base pointer
+- PC：program counter
+- RV: returned value
+
+There are no general-purpose registers; all operations happen on the stack.
+
+## Opcodes
+
+All opcodes are single-byte, except for immediate value instructions.
+
+The instructions supported by FVM are as follows:
+
+### Register Instructions
+
+**sp**
+<br>0x00
+<br>push stack pointer to stack
+
+**ssp**
+<br>0x01
+<br>pop a 64-bit number from stack and set stack pointer to it.
+
+**bp**
+
+**sbp**
+
+**pc**
+
+**rv**
+
+**srv**
+
+### Immediate Number
+
+**imm**
+<br>
+<br>
+
+### Memory
+
+**ld**
+
+**ld8**
+
+**ld16**
+
+**ld32**
+
+
+**st**
+
+**st8**
+
+**st16**
+
+**st32**
+
+### Stack Operations
+
+**dup**
+
+**pop**
+
+**swap**
+
+**over**
+
+**rot**
+
+
+## Call Frame
+
+
+## Pseudo-Opcodes
+
+
-- 
cgit v1.0