From 42c866376fc82a7a7bcdf2e85368469e35595d00 Mon Sep 17 00:00:00 2001
From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Thu, 19 Feb 2026 18:38:18 +0200
Subject: [PATCH] Document virtual machine architecture and components: added
 detailed descriptions of the two-stack design, x86 unreal mode execution,
 memory management using XMS, graphics system, boot process, and virtual CPU
 opcodes.

---
 doc/virtual machine.org | 92 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 76 insertions(+), 16 deletions(-)

diff --git a/doc/virtual machine.org b/doc/virtual machine.org
index fabd2cc..efe17da 100644
--- a/doc/virtual machine.org	
+++ b/doc/virtual machine.org	
@@ -6,26 +6,86 @@
 #+AUTHOR: Svjatoslav Agejenko
 #+LANGUAGE: en
 
-Current emulator emulates:
-- 1 CPU.
-- It has 2 stacks
-- ~50 instructions
-- 4GB flat address space (theoretically).
+* Overview
+
+Fifth is a hobby operating system built around a custom stack-based
+virtual CPU. The virtual CPU emulator runs as a COM executable
+(emulator.com) under MS-DOS.
+
+The virtual machine is designed to be simple yet powerful, featuring
+two stacks (data stack and return stack), approximately 50
+instructions (opcodes), and a theoretical 4GB flat address space. It
+serves as the foundation for the Fifth language — a Forth-inspired,
+interactive programming environment where users can define, extend,
+and modify system behavior at runtime.
+
+* x86 Unreal Mode Execution
+
+The emulator runs as a standard DOS COM executable and uses x86
+real-mode assembly with a technique called "unreal mode" to access
+extended memory beyond the 640KB conventional DOS limit. In unreal
+mode, the CPU operates in real-mode (compatible with DOS) but with
+segment registers configured to allow access to the full 32-bit
+address space (up to 4GB).
+
+Key aspects:
+- Starts in real mode for DOS compatibility.
+- Switches temporarily to x86 protected mode to initialize segment
+  registers for 4 GB RAM flat address space.
+- Returns to real mode while retaining 4 GB RAM access.
+- Uses XMS (Extended Memory Specification) for large memory allocation.
+
+** Memory Management and XMS
+
+The emulator uses DOS XMS (Extended Memory Specification) to allocate
+large blocks of extended memory:
+
+- **XMS Allocation**: Allocates the largest available block of extended
+  memory using HIMEM.SYS
+- **Memory Locking**: Locks the allocated block to prevent swapping
+- **Address Mapping**: Uses xms_addr variable to store the linear
+  address of allocated memory
+- **Virtual-to-Physical**: All virtual CPU addresses are offset by
+  xms_addr to convert to physical memory addresses
+
+* Two-Stack Architecture
+
+The virtual CPU uses two separate stacks:
+
+- **Data Stack**: Main working stack for operations.
+- **Return Stack (variable resp)**: Stores return addresses for
+  subroutine calls.
+
+* Graphics System
+
+The virtual machine integrates directly with VESA BIOS for graphics
+output. It uses VESA 640x480 8-bit color mode.
+
+Graphics operations are performed through dedicated VM instructions.
+
+* Boot Process**
+
+1. DOS loads emulator.com as a COM executable
+2. system_init() allocates XMS memory and sets up A20 gate
+3. Sets VESA graphics mode (640x480, 8-bit color)
+4. Loads first kilobyte of kernel (core.raw) from disk into beginning
+   of virtual RAM.
+5. Jumps to kernel entry point
+6. Kernel loads remaining 3 kibibytes of kernel bytecode into RAM. So
+   initial bytecode part of the kernel must not exceed 4 kibibytes.
+7. Kernel loads high-level Fifth boot code into RAM.
+8. Kernel starts compiling additional modules to itself from
+   high-level bytecode to gain filesystem support, dynamic RAM support
+   and other essential functions.
+9. Additional modules (keyboard / mouse drivers) and interactive shell
+   are now loaded from filesystem files.
+10. Enters interactive REPL
 
 
-While I tried to keep instruction set simple, I was forced to put in
-some complex instructions to make performance acceptable on
-emulator.
-
-CPU has following registers:
-- IP :: instruction pointer
-- DSP :: data stack pointer
-- RSP :: return stack pointer
-
 * Implemented instructions
 
-Virtual CPU, commands (most of them are avaiable as ordinary commands
-in programming language):
+Virtual CPU opcodes (most of them are available as directly executable commands
+in FIFTH programming language):
 
 
 |  # | Name     | Stack effect          | Description                                              | Notes                                                               |
-- 
2.20.1