Fifth is a self-hosted hobby operating system built around a
Forth-inspired programming language. It runs on a custom 32-bit
-stack-based virtual CPU, emulated on x86 DOS real mode. The system
-integrates a kernel (compiler + interpreter), a virtual machine
-emulator, device drivers, graphics libraries, a filesystem, a text
-editor, and a graphics editor.
+stack-based virtual CPU, emulated on x86 DOS real mode.
-# Key Conventions and Warnings
+# Build Commands
+
+## Compile Emulator (x86 assembly)
+
+```bash
+cd emulator && bash compile.sh
+```
+Requires FASM (Flat Assembler). Produces `emulator.com` (DOS COM binary).
+
+## Compile Kernel (Virtual CPU assembly)
+
+```bash
+cd kernel && bash compile.sh
+```
+Produces `core.raw` (kernel bytecode).
+
+## Run Under QEMU
+
+```bash
+bash "floppy image/run under qemu.sh"
+```
+
+## Mount/Unmount Floppy Image
+
+```bash
+bash "floppy image/image mount.sh"
+bash "floppy image/image umount.sh"
+```
+
+## Convert Fifth Source Files
+
+```bash
+# FSCII → readable source
+fbc Tools/5th2src.bas filename # creates filename.src
+
+# Readable source → FSCII
+fbc Tools/src25th.bas filename # creates filename.5th
+```
+
+# Testing
+
+This project has no automated test suite. Testing is manual via QEMU
+emulation.
+
+# Code Style Guidelines
+
+## Assembly Files (x86 - emulator/)
-1. *Do NOT edit =.html= files.* They are generated from =.org= files.
- Always edit the =.org= source instead.
+- **Format**: FASM (Flat Assembler) syntax
+- **Comments**: Use `;` for comments. Add header comment block for each file.
+- **Labels**: Use descriptive names with underscores (e.g., `op_02_kbd@`)
+- **Indentation**: Use tabs for instruction alignment
+- **Include order**: Main file includes opcode files, then utility files
+- **Register conventions**:
+ - `esi` = instruction pointer (virtual CPU)
+ - `edi` = data stack pointer (virtual CPU)
+ - `es` = 0 (flat memory access)
+- **Always jump back to `emu` label after opcode execution**
-2. *Files under =imageFile/f/= appear as plain text in the repo but
- use FSCII encoding internally.* The files checked into git are
- human-readable source representations. The actual disk image
- (=disk.raw=) uses FSCII encoding. The conversion tools
- (=src25th.bas=, =5th2src.bas=) handle translation. When editing
- Fifth source files in =imageFile/f/=, write standard ASCII text —
- the build tools handle FSCII conversion.
+## Assembly Files (Virtual CPU - kernel/)
-3. *Two different assembly languages exist in this project:*
- - =kernel/core.asm= and =kernel/define.asm= use
- the *virtual CPU's* own instruction set (NOT x86). See the
- "Virtual CPU Instruction Set" section below.
- - =emulator/emulator.asm= and related =*.asm= files under emulator/ directory
- are *x86 real-mode* DOS assembly for FASM (Flat Assembler).
+- **Format**: FASM syntax with custom opcode macros from `define.asm`
+- **Macros**: Use `xnum`, `xcall`, `xjmp`, `xif`, `xret` etc.
+- **Labels**: Use `l` prefix for internal labels (e.g., `lload`, `lmain`)
+- **Org**: Code starts at `org 0`
-4. *Binary files* (=.raw=, =.com=, =.dat=, =FNT_SYSTEM=,
- =I01_MCARROW=, =core.raw=, =emulator.com=) are compiled outputs
- or binary data — do not edit them directly.
+## Fifth Source Files (imageFile/f/)
-5. The project uses *spaces in directory names* (e.g.,
- ="floppy image/"=). Always quote paths in shell commands.
+- **Numbers**: All literals are hexadecimal by default (e.g., `FF` = 255)
+- **Word definitions**: `: wordname ... ;`
+- **Comments**: Use `\` for line comments, `( )` for inline comments
+- **Stack effects**: Document as `( before -- after )` at word start
+- **Naming**: Lowercase for standard words, can use mixed case for user words
+- **Spacing**: Use tabs for indentation within definitions
+- **Immediate words**: Mark with `im` at end of definition
-6. *Numbers in Fifth source are hexadecimal by default*, not decimal.
- For example, =FF= means 255, =400= means 1024, =3B= means 59.
- The language has a =d.= word for decimal display but all literals
- in source code are hex.
+## FSCII Encoding
+
+Files in `imageFile/f/` use special encoding internally:
+- Bytes 0-15 = hex digits 0-F
+- Byte 253 (FD) = tab
+- Byte 254 (FE) = newline/carriage return
+- Byte 255 (FF) = space
+
+Write standard ASCII when editing; conversion tools handle encoding.
+
+# Key Conventions and Warnings
+
+1. **Do NOT edit `.html` files**. They are generated from `.org` files.
+ Always edit the `.org` source.
+
+2. **Two different assembly languages exist**:
+ - `kernel/*.asm` = Virtual CPU's instruction set (NOT x86)
+ - `emulator/*.asm` = x86 real-mode DOS assembly for FASM
+
+3. **Binary files** (`.raw`, `.com`, `.dat`, `FNT_SYSTEM`, `core.raw`,
+ `emulator.com`) are compiled outputs — do not edit directly.
+
+4. **Directory names have spaces** (e.g., `"floppy image/"`). Always
+ quote paths in shell commands.
+
+5. **Numbers in Fifth source are hexadecimal by default**, not decimal.
+ Use `d.` word for decimal display.
# Documentation
-- =doc/index.org= — Project overview, installation, architecture.
-- =doc/language.org= — Complete Fifth language reference (all
- commands, stack effects, examples).
-- =doc/virtual machine.org= — Virtual CPU architecture.
-- =doc/5TH_ET.txt= — Example Fifth source (text editor).
-
-
-# Components — Detailed File Map
-
-## Kernel (Virtual CPU assembly — NOT x86)
-| File | Description |
-|---------------------|------------------------------------------------|
-| =kernel/core.asm= | Main kernel: compiler, interpreter, core words |
-| =kernel/define.inc= | Virtual CPU opcode macro definitions (FASM) |
-| =kernel/font.asm= | 8×8 bitmap font data (256 characters) |
-| =kernel/core.raw= | Compiled kernel binary (do not edit) |
-
- ## Emulator (x86 real-mode FASM assembly)
- | File | Description |
- |------------------------------|-----------------------------------------------------------------|
- | =emulator/emulator.asm= | Main emulator: instruction dispatch loop |
- | =emulator/system.asm= | XMS allocation, protected mode, A20 gate |
- | =emulator/kbdrive.asm= | Keyboard interrupt handler + ring buffer |
- | =emulator/vidput.asm= | Image-to-image blit (opaque) |
- | =emulator/tvidput.asm= | Image-to-image blit (with transparency support, FF=transparent) |
- | =emulator/charput.asm= | Character glyph rendering to image buffer |
- | =emulator/opcodes_00_09.asm= | Implementation for virtual machine opcodes 0-9. |
- | =emulator/opcodes_10_19.asm= | Implementation for virtual machine opcodes 10-19. |
- | =emulator/opcodes_20_29.asm= | Implementation for virtual machine opcodes 20-29. |
- | =emulator/opcodes_30_39.asm= | Implementation for virtual machine opcodes 30-39. |
- | =emulator/opcodes_40_49.asm= | Implementation for virtual machine opcodes 40-49. |
- | =emulator/compile.sh= | Emulator build script |
- | =emulator/emulator.com= | Compiled DOS COM binary (do not edit) |
-
-
-## High-Level Boot Code (Fifth language)
-| File | Description |
-|-----------------------------|-------------------------------------------------------------------|
-| =imageFile/f/5th_boot= | Core language: compiler, strings, dynamic memory, filesystem, FAT |
-| =imageFile/f/5TH_AUTORUN= | Startup script: loads drivers, shows logo, enters REPL |
-| =imageFile/f/5TH_QUICKPATH= | Shortcut path definitions for navigation |
-
-## Applications (Fifth language)
-| File | Description |
-|-------------------------|--------------------------------------------|
-| =imageFile/f/5th_et= | Full-screen text editor (ET command) |
-| =imageFile/f/5th_eg= | Graphics editor (gedit/geditnew commands) |
-| =imageFile/f/5th_logo= | Draws the Fifth logo on screen at startup |
-| =imageFile/f/5th_demo= | Demo programs (graphics test, mouse test) |
-
-## Libraries (Fifth language, in =imageFile/f/lib/=)
-| File | Description |
-|--------------------|---------------------------------------------------------------|
-| =5th_gfx= | Core graphics: screen buffer, palette, text output, scrolling |
-| =5th_gfx2= | Extended graphics: lines, boxes, flood fill, flip |
-| =5th_trig= | Trigonometry: sin/cos lookup table |
-| =5TH_DRVKBD= | Keyboard driver: scan code reading, layout loading |
-| =5TH_DRVMOUSE= | Mouse driver: position tracking, click regions |
-| =5TH_KBD_US= | US QWERTY keyboard layout scan code → FSCII table |
-| =5TH_KBD_USDVORAK= | US Dvorak keyboard layout table |
-| =5TH_UICMD= | Command-line UI: =words=, =cmdline=, =fs.=, =bye= |
-
-## Help/Data Files
-| File | Description |
-|-------------------------|----------------------|
-| =imageFile/f/txt_help= | General help text |
-| =imageFile/f/txt_et= | Text editor help |
-| =imageFile/f/txt_eg= | Graphics editor help |
-
-## Binary Assets (do not edit)
-| File | Description |
-|----------------------------|--------------------------|
-| =imageFile/f/FNT_SYSTEM= | System font binary |
-| =imageFile/f/I01_MCARROW= | Mouse cursor arrow image |
-
-# Tools (QuickBASIC / FreeBASIC)
-
-| File | Purpose |
-|----------------------|--------------------------------------------------|
-| =tools/5th2src.bas= | Convert FSCII file → readable =.src= text file |
-| =tools/src25th.bas= | Convert readable =.src= text → FSCII =.5th= file |
-| =tools/fsimport.bas= | Import a host file into =disk.raw= virtual disk |
-| =tools/editor.bas= | Source code editor utility |
-| =tools/font.dat= | Font data used by editor tool |
-
-## FSCII ↔ Source Conversion Details
-
-=5th2src.bas= converts: byte 0–9 → ASCII "0"–"9", byte 10–15 →
-ASCII "A"–"F", byte 255 → space, byte 253 → tab, byte 254 → newline.
-Everything else passes through as-is.
-
-=src25th.bas= does the reverse: tries to interpret words as hex
-numbers (converting ASCII "0"–"9" → bytes 0–9, "A"–"F" → bytes
-10–15), space → byte 255, tab → byte 253, newline → byte 254.
-
-# Building & Running
-
-## Compile the Emulator
-
- cd emulator && bash compile.sh
-
-Requires FASM (Flat Assembler). Produces =emulator.com= (DOS COM).
-## Run Under QEMU
+- `doc/index.org` — Project overview, installation, architecture
+- `doc/language.org` — Complete Fifth language reference
+- `doc/virtual machine.org` — Virtual CPU architecture
+- `doc/opcodes_00_09.org` through `doc/opcodes_40_49.org` — Opcode details
- bash "floppy image/run under qemu.sh"
+# File Organization
-## Mount/Unmount Floppy Image
+```
+emulator/ # x86 real-mode assembly (FASM)
+kernel/ # Virtual CPU assembly
+imageFile/f/ # Fifth source files (FSCII encoded)
+imageFile/f/lib/ # Fifth libraries
+doc/ # Org-mode documentation (edit .org, not .html)
+Tools/ # QuickBASIC utilities for file conversion
+floppy image/ # QEMU scripts, disk images
+```
+
+# Common Tasks
+
+## Adding a New Opcode
+
+1. Implement in `emulator/opcodes_XX_XX.asm`
+2. Add entry to dispatch table in `emulator/emulator.asm`
+3. Add macro in `kernel/define.asm`
+4. Document in `doc/opcodes_XX_XX.org`
+5. Add high-level word in `imageFile/f/5th_boot` if needed
+
+## Adding a New Fifth Word
+
+1. Define in appropriate file under `imageFile/f/`
+2. Include stack effect comment: `: wordname ( a b -- result )`
+3. For library words, add to file in `imageFile/f/lib/`
+4. Test by running in QEMU
+
+# Error Handling
- bash "floppy image/image mount.sh"
- bash "floppy image/image umount.sh"
+- Fifth has no exception system. Check return values explicitly.
+- Use `?` to inspect memory: `address ?`
+- Use `depth.` to check stack balance
+- Errors typically crash or hang the VM — test incrementally
projects / fifth.git / commitdiff