HalfaxOS

A 64-bit capability-based operating system written from scratch in C and x86_64 Assembly. No Linux, no BSD — every line is original.

What It Is

HalfaxOS is a bare-metal OS kernel with a capability-based security model, message-passing IPC, and Ring 3 userspace — designed from day one to avoid the mistakes of UNIX and Windows. As of v0.10 it has a microkernel shape: the kernel owns hardware + spawn(caps) → process; the desktop compositor (/bin/wm_srv), the terminal emulator (/bin/term_app), and the shell (/bin/hsh) are all Ring-3 programs holding capabilities. See truth.md for the full design philosophy.

Core features:

• Capability handles — typed, permission-checked handles replace raw file descriptors
• Capability-region memory boundary — no raw user pointers; memory crosses as (region, offset, len); sealable + revocable regions
• Message-passing IPC — named ports with structured messages, no signals
• Ring 3 userspace — per-process address spaces, ELF64 loader, spawn/wait (no fork), console-as-capability stdio, and /bin/hsh the Ring-3 shell
• 52 syscalls (0–52; #46 reserved) — minimal, orthogonal (vs Linux's 450+)
• Preemptive single-CPU scheduler — IRQ-safe, hardened, per-process CR3 switching
• Framebuffer GUI — Ring-3 compositor (wm_srv) with window titles + Menu, Ring-3 terminal emulator (term_app) hosting the shell via console-over-IPC
• TCP/IP networking — E1000 NIC, ARP, IPv4, UDP, TCP, ICMP, DNS, HTTP
• Filesystem — VFS layer, RAM filesystem, device filesystem, exFAT driver
• ACPI/APIC — multi-core CPU detection, IOAPIC routing
• Boots via GRUB2 Multiboot2 (BIOS/UEFI hybrid ISO)
• Works in VMware Workstation and on physical hardware

---

Architecture

GRUB Multiboot2
  └── boot.asm              (32→64 bit transition, page tables, long mode)
        └── kernel_main (C)
              ├── Capability System    (cap.c — object pool, handle tables, permissions)
              ├── ACPI / APIC / SMP    (multi-core detection and routing)
              ├── GDT / IDT / TSS / PIC
              ├── Memory Management
              │     ├── PMM            (bitmap page allocator)
              │     ├── VMM            (4-level paging, per-process address spaces)
              │     └── Kernel Heap    (kmalloc / kfree)
              ├── Task Scheduler       (preemptive, Ring 0/3, CR3 switching)
              ├── System Calls         (int 0x80, 52 syscalls)
              ├── IPC                  (named ports, typed messages, cap transfer)
              ├── Drivers
              │     ├── Framebuffer    (VBE/VESA via Multiboot2)
              │     ├── PS/2 Keyboard + Mouse
              │     ├── PIT Timer
              │     ├── PCI Enumeration
              │     └── Intel E1000 NIC
              ├── Networking
              │     ├── Ethernet / ARP / IPv4
              │     ├── UDP / TCP / ICMP
              │     ├── DNS resolver / HTTP client
              │     └── DHCP client
              ├── Filesystem
              │     ├── VFS layer      (capability-protected file operations)
              │     ├── RAM filesystem (ramfs)
              │     ├── Device filesystem (devfs)
              │     └── exFAT driver
              ├── GUI
              │     ├── Graphics primitives
              │     ├── Window Manager (drag, edge/corner resize, close, z-order)
              │     ├── Desktop + Taskbar
              │     └── Terminal       (multi-window, scrollback)
              └── Userspace
                    ├── ELF64 loader
                    ├── Userlib        (syscall wrappers + cap API)
                    └── Programs       (14 embedded — wm_srv, term_app, hsh, demos/tests; table below)

---

Capability Handle System

HalfaxOS replaces UNIX file descriptors with typed, permission-checked capability handles. This is the central architectural decision — see truth.md §2, §3, §7.

┌─────────────────────────────────────────────────┐
│  Process A (task_t)                             │
│  handles[128]:                                  │
│    [0] CAP_FILE  /etc/motd  perms=RW_SC  ref=2 │
│    [1] CAP_FILE  /etc/motd  perms=R__SC  ref=2 │  ← attenuated dup
│    [2] CAP_PORT  port=5     perms=SR___  ref=1 │
│    ...                                          │
│  Every read/write/seek/close → cap_check()      │
└─────────────────────────────────────────────────┘

Object types:  FILE, DIR, PORT, WINDOW, TIMER, PROCESS, SHMEM, DEVICE
Permission bits: READ, WRITE, SEEK, CLOSE, SEND, RECV, RESIZE, TRANSFER, EXEC, SIGNAL, MAP, STAT

Key properties:

• cap_dup() can only reduce permissions, never escalate
• cap_transfer() / ipc_send_cap() pass handles between processes
• cap_close_all() cleans up on process exit (refcounted kernel objects)
• All VFS operations are permission-gated — no ambient authority

---

Userspace Programs

ELF64 programs (14) are embedded in the kernel and installed to /bin/:

Program	Description
hello	Basic Ring 3 test — prints, sleeps, exits
fibonacci	Computes Fibonacci numbers via syscalls
primes	Trial division prime finder
ipc_echo	IPC echo server demo — creates port, receives messages
cap_demo	Capability demo — open, info, dup, attenuated write denial, read, close
region_test	Capability-region boundary — read via region, seal, revoke
spawn_test	Spawns /bin/child, waits, reads its exit code (no fork)
child	Tiny child for spawn_test/hsh — prints, exits 42
echo_test	Console stdio — reads fd 0, writes fd 1 to its own window
hsh	The Halfax Shell — reads its console, spawns + waits programs
win_demo	CAP_WINDOW demo — creates a window, draws, event loop (v0.8)
wm_srv	The Ring-3 compositor — owns the display, serves the window protocol on the "wm" port, Menu + shutdown (v0.9–v0.10)
app_demo	wm_srv client demo — bouncing ball via the window protocol
term_app	Ring-3 terminal emulator — wm_srv client window hosting /bin/hsh via console-over-IPC (v0.10)

Run an individual program with exec /bin/<name> in the terminal. The program model (regions, spawn/wait, console stdio, hsh) is exercised end-to-end by the "HalfaxOS (test mode)" GRUB entry (the test cmdline harness).

---

Terminal Commands

Historical (v0.7-era): these are the in-kernel terminal's commands. Since v0.10 the desktop terminal is /bin/term_app hosting /bin/hsh, which has exit/help builtins and runs programs by name (hello, win_demo, …). The kernel terminal is dormant (only runs pre-wm_srv).

System

• about — system information (CPU, RAM, uptime)
• hwinfo — detailed hardware inventory
• mem — memory usage
• uname — OS/architecture info
• uptime — system uptime
• dmesg / dmesg -w — kernel log (follow mode)

Process Management

• ps — list running processes
• kill <PID> — terminate process
• exec <path> — run ELF64 binary from VFS

Filesystem

• ls [path] — list directory
• cat <file> — display file contents
• mkdir <path> — create directory
• rm <path> — remove file/directory
• touch <file> — create empty file
• cd <path> / pwd — change/print working directory
• hexdump <file> — hex dump of file

Networking

• ifconfig — network interface status
• dhcp — request IP address
• ping <IP> — ICMP echo request
• dnslookup <host> — DNS hostname resolution
• nslookup <host> — alias for dnslookup
• curl <URL> — HTTP GET with inline DNS/TCP progress
• lspci — PCI device list

IPC & Capabilities

• ports — list IPC ports
• mkport <name> — create named port
• msgsend <port> <text> — send message
• msgrecv <port> — receive message
• handles — list open capability handles for current task
• capinfo <H> — detailed info for handle H (type, perms, refcount)

GUI

• term — open new terminal window
• clear — clear terminal
• refresh — force desktop redraw
• resolution — show/change screen resolution
• help — full command list

---

Build

Requirements

• Docker Desktop for Windows (recommended), or
• WSL2 / Linux with build-essential nasm xorriso grub-pc-bin mtools

Windows + Docker

cd C:\Users\arhal_iz5093n\Desktop\projects\33rd
.\build-windows.ps1

Linux / WSL2

make iso

Output: output/halfaxos.iso (~19.5 MB)

---

Running in VMware Workstation

1. File → New Virtual Machine → Typical
2. Select Installer disc image → output/halfaxos.iso
3. Guest OS: Other → Other 64-bit
4. RAM: 512 MB (256 MB minimum)
5. CPU: 2 cores (SMP supported)
6. Power on — boots directly to HalfaxOS desktop

---

Source Layout

src/
  boot/           boot.asm, interrupts.asm, ap_trampoline
  kernel/         kernel.c, task.c, syscall.c, cap.c, ipc.c, elf.c, usermode.c
  cpu/            gdt, idt, pic, acpi, apic, smp, tss, cpuinfo
  mm/             pmm, vmm, kheap
  drivers/
    fb/           framebuffer
    input/        keyboard, mouse
    timer/        pit, apic_timer
    net/          e1000
    pci/          pci enumeration
  net/            ethernet, arp, ip, udp, tcp, icmp, dns, http
  fs/             vfs, ramfs, devfs, exfat
  gui/            gfx, wm, terminal
  lib/            string, kprintf, userlib
  user/           14 embedded programs (hello … hsh, win_demo, wm_srv, app_demo, term_app) + user.ld
  input/          input_worker

---

System Call Table (52 syscalls, 0–52; #46 reserved)

#	Name	Description
0	EXIT	Terminate process
1	WRITE	Write to handle
2	READ	Read from handle
3	OPEN	Open file → capability handle
4	CLOSE	Close capability handle
5	YIELD	Yield CPU
6	SLEEP	Sleep (ms)
7	GETPID	Get process ID
8–10	(FORK, EXEC, WAIT)	Defined, never dispatched — no fork model; use SPAWN/WAITPID (44/45)
11	KILL	Kill process
12–14	(MMAP, MUNMAP, BRK)	Defined, never dispatched — memory crosses as region caps (39–43)
15	GETTIME	System time (ticks)
16	WIN_BLIT	Blit region-cap pixels into a window canvas
17	WIN_PRESENT	Mark window canvas dirty → repaint
18	WIN_CREATE	Create window → CAP_WINDOW handle
19	WIN_DESTROY	Release CAP_WINDOW handle
20	WIN_EVENT	Pop window event (blocks)
21	STAT	Stat path
22	FSTAT	Stat handle
23–25	MKDIR, UNLINK, READDIR	Directory operations
26–28	SEEK, GETCWD, CHDIR	File position, working directory
29–34	IPC_CREATE..IPC_FIND	Message-passing IPC
35	CAP_DUP	Duplicate handle with attenuated perms
36	CAP_INFO	Query handle type/perms/refcount
37	CAP_TRANSFER	Transfer handle to another process
38	IPC_SEND_CAP	Transfer handle via IPC message
39	MEM_DEFAULT	Get the task's default region handle
40	MEM_CREATE	Create a new mapped region → handle
41	MEM_SEAL	Freeze a region write-once
42	MEM_REVOKE	Kernel refuses all further access to a region
43	MEM_INFO	Region user-VA (so userland can address it)
44	SPAWN	Spawn a program → CAP_PROCESS handle (no fork)
45	WAITPID	Block on a process handle → child exit code
46	(reserved)	Was SYS_FB_GET — removed for exposing raw framebuffer MMIO to Ring 3
47	INPUT_OPEN	CAP_PORT handle to the kernel input event stream
48	DISPLAY_ACQUIRE	CAP_SHMEM back-buffer + framebuffer info (the compositor path)
49	DISPLAY_PRESENT	Blit back-buffer region → screen (kernel owns the MMIO)
50	DISPLAY_SET_ACTIVE	Toggle Ring-3 vs kernel ownership of the screen
51	POWEROFF	ACPI S5 soft-off (privileged; does not return)
52	CONSOLE_BIND	Bind caller's stdio to IPC ports (Ring-3 terminal model)

The capability-region syscalls (39–43) are the user/kernel memory boundary — no other syscall takes a raw user pointer; memory crosses as (region, off, len).

---

Project Structure

33rd/
├── build-windows.ps1        PowerShell build launcher (Docker)
├── Dockerfile               Docker build environment
├── Makefile                 Native build configuration
├── linker.ld                Kernel linker script
├── truth.md                 Design principles & implementation status
├── ARCHITECTURE.md          Technical architecture documentation
├── CHANGELOG.md             Version history
├── RING3_IMPLEMENTATION.md  Ring 3 implementation details
├── config/
│   └── grub.cfg             GRUB bootloader configuration
├── src/                     Source code (see layout above)
└── output/
    └── halfaxos.iso         Build output