From db4989bc23b876a7caafca955b2355338e2ec655 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Sun, 15 Feb 2026 01:41:27 +0200 Subject: [PATCH] Expanded and restructured `AGENTS.org` for improved clarity and detail. Updated licensing in `5th_logo`. Adjusted quick path definitions in `5TH_QUICKPATH`. --- AGENTS.org | 474 ++++++++++++++++++++++++++++++++++---- imageFile/f/5TH_QUICKPATH | 1 - imageFile/f/5th_logo | 2 +- 3 files changed, 431 insertions(+), 46 deletions(-) diff --git a/AGENTS.org b/AGENTS.org index 937b5fe..f53c41b 100644 --- a/AGENTS.org +++ b/AGENTS.org @@ -1,64 +1,450 @@ -- Primary documentation is stored in *.org files (they use emacs - org-mode syntax). All html files are compiled from org, so you - better read and write org files instead of html. +#+TITLE: AGENTS — Fifth Operating System Project Guide +#+AUTHOR: Guide for AI coding assistants (Aider, etc.) -* Components -** Kernel +* Project Overview -Kernel is minimal viable implementation of fifth language compiler and -interpreter. It is immediately loaded when virtual machine starts. +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. -- *kernel/core.asm*: Main kernel code in virtual CPU own Assempbly - language. -- *kernel/define.inc*: Machine code definitions for the virtual CPU - instructions. +* Key Conventions and Warnings -** Emulator +** CRITICAL — Read Before Making Any Changes -The virtual CPU emulator. +1. *Do NOT edit =.html= files.* They are generated from =.org= files. + Always edit the =.org= source instead. -- *emulator/emulator.asm*: Main emulator code that interprets Fifth - machine code and interfaces with host system resources. +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. -** Drivers +3. *Two different assembly languages exist in this project:* + - =kernel/core.asm= and =kernel/define.inc= use the *virtual CPU's + own instruction set* (NOT x86). See the "Virtual CPU Instruction + Set" section below. + - =emulator/emulator.asm= and its =.inc= files are *x86 real-mode + DOS assembly* for FASM (Flat Assembler). -Hardware interface components that handle input and output devices. +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. -- *imageFile/f/lib/5TH_DRVKBD*: Keyboard driver that translates scan - codes into Fifth's character encoding (FSCII). -- *imageFile/f/lib/5TH_DRVMOUSE*: Mouse driver that tracks cursor - position and button states for graphical interaction. +5. The project uses *spaces in directory names* (e.g., + ="floppy image/"=). Always quote paths in shell commands. -** Graphics Libraries +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. -Components responsible for rendering visual elements. +** 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). -- *imageFile/f/lib/5th_gfx*: Basic 2D graphics functions including - drawing lines, boxes, and image manipulation. -- *imageFile/f/lib/5th_gfx2*: Advanced graphics routines for more - complex rendering operations. +* FSCII Character Encoding -** Utility Libraries +Fifth uses FSCII (Fifth Standard Code for Information Interchange) +instead of ASCII. Key differences: -Specialized mathematical and data processing functions. +| Dec | Hex | FSCII Function | +|------+-----+---------------------------------------------| +| 0–15 | 0–F | Hex digit characters (not control codes!) | +| 252 | FC | Backspace | +| 253 | FD | Tabulator (TAB) | +| 254 | FE | Carriage return (newline) | +| 255 | FF | Space | +| else | | Same as ASCII (letters, punctuation, etc.) | -- *imageFile/f/lib/5th_trig*: Trigonometric functions (sin, cos). +This means: ASCII space (32) is NOT space in FSCII. The character "0" +(ASCII 48) is an ordinary letter, not the number zero. Hex digits 0–F +are represented by byte values 0–15. -** Tools -Utilities for development and maintenance of the Fifth system. +* Virtual CPU Instruction Set -- *tools/5th2src.bas*: Converts system files (FSCII encoded) into - human-readable source code format. -- *tools/fsimport.bas*: Imports external files into the Fifth system's - virtual disk image. -- *tools/src25th.bas*: Converts source code back into system-compatible - FSCII encoded files. +The virtual CPU is stack-based with two stacks: a data stack (=edi= +register in emulator) and a return stack (=resp=). Instructions are +single-byte opcodes, some followed by a 32-bit argument. -** Documentation +Opcodes defined in =kernel/define.inc= and dispatched in +=emulator/emulator.asm=: + +| Opcode | Mnemonic | Args | Stack Effect | Description | +|--------+----------+--------+---------------------------+-----------------------------------| +| 0 | xnop | | ( -- ) | No operation | +| 1 | xhalt | | | Halt / exit | +| 2 | kbd@ | | ( -- scancode ) | Read keyboard scancode | +| 3 | xnum | 32-bit | ( -- n ) | Push literal number | +| 4 | xjmp | 32-bit | | Unconditional jump | +| 5 | xcall | 32-bit | | Call subroutine (push return) | +| 6 | xinc | | ( n -- n+1 ) | Increment TOS | +| 7 | xdec | | ( n -- n-1 ) | Decrement TOS | +| 8 | xdup | | ( n -- n n ) | Duplicate TOS | +| 9 | xdrop | | ( n -- ) | Drop TOS | +| 10 | xif | 32-bit | ( flag -- ) | Jump if flag = 0 | +| 11 | xret | | | Return from subroutine | +| 12 | xc@ | | ( addr -- byte ) | Fetch byte from memory | +| 13 | xc! | | ( byte addr -- ) | Store byte to memory | +| 14 | xpush | | ( n -- ) R:( -- n ) | Move TOS to return stack | +| 15 | xpop | | ( -- n ) R:( n -- ) | Move from return stack to TOS | +| 17 | xrot | | ( a b c -- b c a ) | Rotate top 3 (note: non-standard) | +| 18 | xdisk@ | | ( sector mem -- ) | Load 1024 bytes from disk | +| 19 | xdisk! | | ( mem sector -- ) | Save 1024 bytes to disk | +| 20 | x@ | | ( addr -- n ) | Fetch 32-bit from memory | +| 21 | x! | | ( n addr -- ) | Store 32-bit to memory | +| 22 | xover | | ( a b -- a b a ) | Copy second to top | +| 23 | xswap | | ( a b -- b a ) | Swap top two | +| 24 | xplus | | ( a b -- a+b ) | Add | +| 25 | xminus | | ( a b -- a-b ) | Subtract | +| 26 | xmul | | ( a b -- a*b ) | Multiply (signed) | +| 27 | xdiv | | ( a b -- a/b ) | Divide (signed) | +| 28 | xcmpg | | ( a b -- flag ) | Greater than | +| 29 | xcmpl | | ( a b -- flag ) | Less than | +| 30 | xnot | | ( n -- ~n ) | Bitwise NOT | +| 31 | xi | | ( -- n ) | Copy return stack TOS | +| 32 | xcprt@ | | ( port -- byte ) | Read I/O port | +| 33 | xcprt! | | ( byte port -- ) | Write I/O port | +| 34 | xi2 | | ( -- n ) | Copy return stack 2nd | +| 35 | xi3 | | ( -- n ) | Copy return stack 3rd | +| 36 | xshl | | ( n count -- n<>count ) | Shift right | +| 38 | lor | | ( a b -- a OR b ) | Bitwise OR | +| 39 | lxor | | ( a b -- a XOR b ) | Bitwise XOR | +| 40 | xvidmap | | ( addr -- ) | Map image buffer to VESA video | +| 41 | xmouse@ | | ( -- btns dy dx ) | Read mouse state | +| 42 | xvidput | | ( src dst x y -- ) | Blit image to image | +| 43 | xcmove | | ( src dst count -- ) | Copy memory bytes | +| 44 | xcfill | | ( byte addr count -- ) | Fill memory with byte | +| 45 | xtvidput | | ( src dst x y -- ) | Transparent blit (FF=transparent) | +| 46 | xdep | | ( -- depth ) | Data stack depth | +| 47 | xcharput | | ( fg bg font dst x y -- ) | Render character glyph | + +* Fifth Language Quick Reference + +Fifth is Forth-like: postfix notation, stack-based, words separated by +spaces. Key syntax patterns found in the source code: + +** Defining Words +#+begin_example +: name ... ; \ Define a new word (subroutine) +:i name ... ; \ Define immediate word (runs at compile time) +var name \ Define a 32-bit variable (initialized to 0) +N vari name \ Define a variable initialized to N +N const name \ Define a constant +create name N alloc \ Allocate N bytes of data space +str content" name \ Define a string constant +Dstr content" name \ Define a dynamic string constant +#+end_example + +** Control Flow +#+begin_example +if ... then \ Conditional +if ... else ... then \ Conditional with else +N do ... loop \ Count down from N-1 to 0 (i = counter) +low high for ... loop \ Count up from low to high-1 (i = counter) +until ... loop \ Repeat until "done" is called +#+end_example + +** Stack Manipulation +#+begin_example +dup drop swap over rot 2dup 2drop nip +push pop \ Move to/from return stack +i i2 i3 \ Copy from return stack (loop counters) +#+end_example + +** Memory +#+begin_example +@ ! \ 32-bit fetch/store +c@ c! \ 8-bit fetch/store +cmove \ Block copy ( src dst count -- ) +cfill \ Block fill ( byte addr count -- ) +#+end_example + +** Comments +#+begin_example +\ single line comment (to end of line) +( comment until closing paren ) +.( visible message ) \ Print at compile time +#+end_example + +** Important Idioms in the Codebase +#+begin_example +rh name \ Remove word "name" from dictionary (hide it) + \ Used extensively to keep namespace clean +modulechk \ Load a module if not already loaded +include \ Execute code from a file +D> word \ Parse next word into default dynamic string +D" string" \ Parse string into default dynamic string +#+end_example + +* Disk Layout and Filesystem + +Constants from =5th_boot=: + +| Symbol | Hex Value | Description | +|----------+---------------------------------+--------------------------------------------------| +| fsroot | 24*400 | Root directory location (sector 24h × 1024) | +| fsfatbeg | 25 | FAT starts at sector 25h | +| fsfatsiz | 4000 | FAT size (4000h entries) | +| fsdata | fsfatbeg + fsfatsiz*4/400 + 1 | Data area start sector | + +Sector size is 1024 bytes (=400h=). FAT entry values: +- =-2= — last sector of a file chain +- =-1= — free/unused sector +- =0+= — pointer to next sector + +File directory entry (32 bytes): +| Offset | Size | Content | +|--------+------+-------------------------------------------------| +| 0 | 4 | Extension (4-byte FSCII, e.g. "list", "5th_") | +| 4 | 16 | Filename (padded with FF/spaces) | +| 20 | 4 | First block address (FAT chain start) | +| 24 | 4 | File size in bytes | + +Special extensions: ="free"= marks deleted entries, ="list"= marks +directories (subdirectories). + +* Memory Map + +| Address | Size | Description | +|----------+---------+----------------------------------------| +| 0 | ~4096 | Kernel (core.raw) | +| 1500000h | ~32000 | High-level Fifth boot code (5th_boot) | +| 200000h | varies | Core startup messages area | +| 5200000h | | End of dynamic memory space | + +Dynamic memory is managed by the =dynal=/=dynde=/=dynp=/=dyns= words +defined in =5th_boot=. Up to =100h= (256) dynamic blocks. + +* Boot Sequence (detailed) + +1. Emulator (=emulator.com=) starts, allocates XMS, sets VESA 640×480 + 8-bit mode, loads first 1024 bytes of =disk.raw= into virtual + memory at address 0. +2. Kernel (=core.asm=) executes: loads remaining kernel sectors, then + loads high-level boot code (=5th_boot=) at address =1500000h=. +3. =5th_boot= defines the compiler, interpreter, all core words + (arithmetic, stack ops, strings, dynamic memory, filesystem), + then runs =include= on =5TH_AUTORUN=. +4. =5TH_AUTORUN= loads graphics library (=5th_gfx=), displays logo + (=5th_logo=), loads keyboard driver (=5TH_DRVKBD=), loads command + line UI (=5TH_UICMD=), sets up quick paths, and enters interactive + mode. + +* 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.inc= | XMS allocation, protected mode, A20 gate | +| =emulator/vidput.inc= | Image-to-image blit (opaque) | +| =emulator/tvidput.inc= | Image-to-image blit (transparent, FF=skip) | +| =emulator/charput.inc= | Character glyph rendering to image buffer | +| =emulator/kbdrive.inc= | Keyboard interrupt handler + ring buffer | +| =emulator/compile.sh= | Build script (runs =fasm emulator.asm=) | +| =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 +#+begin_src bash +cd emulator && bash compile.sh +#+end_src +Requires FASM (Flat Assembler). Produces =emulator.com= (DOS COM). + +** Run Under QEMU +#+begin_src bash +bash "floppy image/run under qemu.sh" +#+end_src + +** Mount/Unmount Floppy Image +#+begin_src bash +bash "floppy image/image mount.sh" +bash "floppy image/image umount.sh" +#+end_src + +* Graphics System Details + +The screen is a 640×480 (=280h= × =1E0h=) 8-bit indexed color image +buffer, allocated as a dynamic memory block. + +Image buffer format: +| Offset | Size | Content | +|--------+------+-------------------------------| +| 0 | 4 | X size (width) | +| 4 | 4 | Y size (height) | +| 8 | X*Y | Pixel data (1 byte per pixel) | + +Color is calculated with =calccol ( b g r -- c )= which maps RGB +(0–255 each) to a 6×6×6 color cube (216 colors). The palette is set +up by =setupal= in =5th_gfx=. + +Text output uses an 8×8 pixel font. Cursor position is tracked by +=curx= and =cury= variables. The =emit= word is vectored — initially +it writes to the core message area, then =5th_gfx= redirects it to +graphical text rendering via =(emit2=. + +* In-RAM commands dictionary structure + +Each dictionary entry is 24 bytes: + +| Offset | Size | Content | +|--------+------+-------------------------------------------| +| 0 | 4 | Link to previous entry (0=last, -1=empty) | +| 4 | 15 | Name string (padded) | +| 19 | 1 | Type: 0=data, 1=subroutine, 2=immediate | +| 20 | 4 | Entry data (address of code/data) | + +The dictionary is a linked list searched backwards from =lp= (last +pointer). Up to ~1000 entries fit in the 24000-byte dictionary space. + +Type behavior when referenced: +- Type 0 (data): compiles a =xnum= instruction with the address +- Type 1 (subroutine): compiles an =xcall= instruction +- Type 2 (immediate): executes immediately even during compilation + +* Keyboard System + +Scan codes from the hardware keyboard are buffered by =kbdrive.inc=. +The Fifth keyboard driver (=5TH_DRVKBD=) provides: + +- =KBD_@= — read raw scan code +- =KBD_SC2FSCII= — convert scan code to FSCII using layout table +- =KBD_F@= — read FSCII key (with shift/alt modifiers: +100h/+200h) +- =KBD_FW@= — blocking read (waits for keypress) + +Special key codes (FSK — Fifth Standard Keycodes): +| Code | Key | +|-------+-----------| +| 400h | ESC | +| 401h+ | F1, F2... | +| 410h | Up | +| 411h | Right | +| 412h | Down | +| 413h | Left | +| 414h | Insert | +| 415h | Delete | +| 416h | Home | +| 417h | End | +| 418h | Page Up | +| 419h | Page Down | +| FCh | Backspace | +| FDh | Tab | +| FEh | Enter | +| FFh | Space | + +* Common Patterns in Fifth Source Code + +** Module Loading Guard +#+begin_example +D> \listF\listLIB\5TH_GFX modulechk +#+end_example +Loads the module only if not already loaded (checks dictionary). + +** Variable Cleanup with =rh= +#+begin_example +var tmp1 var tmp2 +: myword ... ; rh tmp1 rh tmp2 +#+end_example +=rh= (remove head) hides temporary variables from the dictionary +after they're no longer needed externally. The variables still exist +in memory but can't be found by name. + +** Dynamic String Lifecycle +#+begin_example +myvar Dv \ allocate dynamic string, store handle in myvar +... \ use the string +myvar Df \ deallocate it +#+end_example -System reference materials. +** Vectored Execution (Deferred Words) +#+begin_example +defer cmdline \ create forward reference +... +' (cmdline ' cmdline is \ point it to actual implementation +#+end_example -- *doc/index.org*: Main documentation page providing an overview of - the Fifth system. -- *doc/language.org*: Detailed reference for the Fifth programming - language syntax and commands. +** File Operations +#+begin_example +D" \listF\myfile" fsDloadnew \ load file → new dynamic block +dup dynp \ get pointer to data +swap dynde \ deallocate when done +#+end_example diff --git a/imageFile/f/5TH_QUICKPATH b/imageFile/f/5TH_QUICKPATH index 137bd3c..6aeb94a 100644 --- a/imageFile/f/5TH_QUICKPATH +++ b/imageFile/f/5TH_QUICKPATH @@ -1,5 +1,4 @@ str \listF\" ~f -str \listGAMES\listSauron_Return\" ~game str \listF\listLIB\" ~lib str \" ~r diff --git a/imageFile/f/5th_logo b/imageFile/f/5th_logo index 7d375e1..9977a08 100644 --- a/imageFile/f/5th_logo +++ b/imageFile/f/5th_logo @@ -41,6 +41,6 @@ tmpH ; 7 3 tmplogo 0 18 at! -.( Fifth, Copyright 2003 Svjatoslav Agejenko. All rights reserved.) +.( Fifth, by Svjatoslav Agejenko. Released under CC0.) forget tmpbox update -- 2.20.1