GitHub - isene/SimplicityOS: The Simple OS - based on the Forth programming language

Quick Start

make        # Build the OS
make run    # Run in QEMU (requires QEMU installed)
make debug  # Run with GDB debugging

Philosophy

Simplicity OS is built on three tiers of words:

Kernel Words - Written in x86_64 assembly, provide core primitives
Core Words - Written in RPN, extend the language
User Words - Applications and user-defined words

All operations use Reverse Polish Notation (RPN):

> 3 4 + .
7 ok

> "Hello World" .
Hello World ok

Examples

Stack Operations

> 5 dup .s
<2> 5 5 ok

> drop .s
<1> 5 ok

> 3 swap .s
<2> 3 5 ok

> + .
8 ok

Defining New Words

> "square" [ dup * ] define
ok

> 7 square .
49 ok

> "cube" [ dup square * ] define
ok

> 3 cube .
27 ok

Variables

> 0 [counter] !
ok

> [counter] @ .
0 ok

> 42 [counter] !
ok

> [counter] @ .
42 ok

Control Flow

> "abs" [ dup 0 < if 0 swap - then ] define
ok

> -5 abs .
5 ok

> "countdown" [ begin dup . cr 1 - dup 0 = until drop ] define
ok

> 5 countdown
5
4
3
2
1
ok

Arrays and Types

> { 10 20 30 }
ok

> len .
3 ok

> 1 at .
20 ok

> type-new "point" swap type-name
ok

> "point" [ { rot rot } 4 type-set ] define
ok

> 100 200 point .
[point: 100 200 ] ok

Built-in Editor

Launch the vim-style editor:

> 0 editor           ( new empty buffer )
> "myfile" editor    ( load existing file )

Editor Commands:

Normal mode: h/j/k/l or arrows to move, i for insert, : for command
Insert mode: Type text, Ctrl+C or ESC returns to normal
Command mode: :w filename save, :q quit, :wq save and quit

Disk Operations

> 512 allot [mybuf] !
ok

> 100 [mybuf] @ disk-read    ( read sector 100 )
ok

> [mybuf] @ 100 disk-write   ( write to sector 100 )
ok

Word Categories

See docs/WORDS.md for complete reference.

Kernel Words (Assembly)

Core primitives: + - * / mod dup drop swap . .s @ ! if then else begin while repeat

Core Words (RPN)

Extended operations loaded at boot time.

User Words (Apps)

Applications like editor, hello, invaders.

Architecture

Kernel Words (Assembly)     <- Hardware interface, stack ops, control flow
        |
Core Words (RPN)            <- Higher-level operations
        |
User Words (Apps)           <- Applications, user definitions

Memory Model:

Heap starts at 2MB, grows upward
Stack uses R14 (TOS) + R15 (stack pointer)
Dictionary uses linked list

Type System:

Type	Value	Description
INT	0	Immediate integers
STRING	1	Null-terminated text
REF	2	Word reference (execution token)
ARRAY	3	Counted array of values
USER	4+	User-defined types

Project Structure

/boot      - Bootloader (512 bytes) and stage2
/kernel    - x86_64 assembly kernel (~56KB)
/apps      - Applications in RPN (editor, games)
/tools     - Build utilities
/docs      - Technical documentation

Requirements

NASM (assembler)
QEMU (emulator)
GNU Make

Documentation

WORDS.md - Complete word reference
ARCHITECTURE.md - Technical architecture
RPN-GUIDE.md - RPN programming guide
CLAUDE.md - Development conventions

License

Public domain. Use freely.