#+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 |
projects / fifth.git / commitdiff