*

1 files changed, 48 insertions, 0 deletions

diff --git a/awk/vm/README.md b/awk/vm/README.md
new file mode 100644
index 0000000..e6bd7a1
--- /dev/null
+++ b/awk/vm/README.md
@@ -0,0 +1,48 @@
+# Simple Stack-Based Virtual Machine
+
+This is an implementation of a minimal stack-based virtual machine in AWK, inspired by Forth. The VM provides basic stack manipulation, arithmetic operations, register access, and memory operations.
+
+## Architecture
+
+The VM consists of:
+- A data stack (100 elements)
+- Main memory (1000 cells)
+- Three registers:
+  - A: General purpose register
+  - B: Often used as memory pointer
+  - P: Program pointer, used for sequential memory operations
+
+## Instruction Set
+
+### Stack Operations
+- `DROP` - Remove top item from stack
+- `DUP` - Duplicate top stack item
+- `OVER` - Copy second item to top of stack
+- Numbers are automatically pushed onto the stack
+
+### Arithmetic Operations
+- `+` - Add top two stack items (a b -- a+b)
+- `AND` - Bitwise AND of top two items
+- `XOR` - Bitwise XOR of top two items
+- `NOT` - Bitwise NOT of top item
+- `2*` - Multiply top item by 2 (shift left)
+- `2/` - Divide top item by 2 (shift right)
+
+### Register Operations
+- `A` - Push value of A register onto stack
+- `A!` - Store top stack value into A register
+- `B!` - Store top stack value into B register
+
+### Memory Operations
+- `@` - Fetch from memory address on stack
+- `!` - Store to memory address on stack
+- `@+` - Fetch from memory at P, then increment P
+- `!+` - Store to memory at P, then increment P
+- `@B` - Fetch from memory address in B register
+- `!B` - Store to memory address in B register
+- `@P` - Fetch from memory address in P register
+- `!P` - Store to memory address in P register
+
+### Utility
+- `.` - NO-OP (does nothing)
+- `BYE` - Exit program
\ No newline at end of file