From: Svjatoslav Agejenko Date: Mon, 23 Feb 2026 00:08:31 +0000 (+0200) Subject: Streamline `AGENTS.md`: remove redundant details, restructure for clarity, and add... X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=0be6f5276a44d53817762c25bd5920cb16f14fbc;p=fifth.git Streamline `AGENTS.md`: remove redundant details, restructure for clarity, and add new sections for build, testing, and coding guidelines. --- diff --git a/AGENTS.md b/AGENTS.md index cfc4e11..35e5a23 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,152 +2,151 @@ 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