MerlionOS-Zig

A bare-metal x86_64 operating system kernel written in Zig, inspired by MerlionOS (Rust). Clean reimplementation leveraging Zig's comptime, explicit allocators, and error unions.

Born for AI. Built by AI. Now in Zig.

Prerequisites

• Zig (0.15+)
• QEMU (for testing)
• xorriso (for ISO creation)

# macOS
brew install zig qemu xorriso

Quick Start

zig build run    # Build kernel + ISO, launch in QEMU

For the COM2 AI proxy path:

# Terminal 1: boot QEMU with COM2 on a UNIX socket
zig build run-ai

# Terminal 2: connect the host-side bridge before using aiask/aipoll
python3 tools/ai_proxy.py --socket /tmp/merlionos-ai.sock

# Optional: delegate prompts to an external LLM CLI or script
python3 tools/ai_proxy.py --socket /tmp/merlionos-ai.sock \
  --backend command --command 'your-llm-command --read-stdin'

# Optional: use OpenAI Responses API from the host bridge
OPENAI_API_KEY=... python3 tools/ai_proxy.py --socket /tmp/merlionos-ai.sock \
  --backend openai --openai-model "${OPENAI_MODEL:-gpt-5.4-mini}"

Roadmap

Phase 1: Boot + Output

• Limine boot protocol (higher-half kernel)
• UART serial COM1 driver
• VGA text mode 80x25 with colors and scrolling
• Dual output logging (serial + VGA)
• Kernel panic handler
• Boot verification in QEMU

Phase 2: CPU Setup

• GDT with kernel/user segments + TSS
• IDT with exception handlers (page fault, double fault, etc.)
• 8259 PIC initialization
• PIT timer at 100Hz

Phase 3: Memory Management

• Physical frame allocator (bitmap-based)
• Virtual memory / page table manager
• Kernel heap allocator (std.mem.Allocator interface)

Phase 4: Keyboard + Shell

• PS/2 keyboard driver (comptime scancode table)
• Interactive shell with line editing and history
• Cursor-aware editing: insert, backspace, delete, left/right, home/end
• Commands: help, clear, echo, info, mem, uptime, version
• QEMU monitor verification for extended keys (left, home, end, delete, up, down)

Phase 5: Multitasking

• Task management with context switching
• Cooperative round-robin task switching via yield
• Process commands: ps, spawn, kill
• Scheduler tick accounting
• Round-robin scheduler (IRQ-time PIT-driven preemption)

Phase 6: Filesystem

• In-memory VFS (inode-based)
• /proc (version, uptime, meminfo, tasks)
• /dev (null, zero)
• Shell working directory with cd and pwd
• File commands: ls, tree, cat, mkdir, touch, write, rm, echo > file
• echo > file redirection verified end-to-end in QEMU

Phase 7: Networking

• PCI bus enumeration
• lspci shell command
• e1000/e1000e device detection
• netinfo shell command
• e1000 BAR0 uncached MMIO mapping + CTRL/STATUS register read
• e1000 MAC address register discovery
• e1000 TX/RX DMA descriptor ring initialization
• Raw Ethernet test-frame TX path
• Raw Ethernet RX descriptor polling path
• Ethernet frame receive with external traffic validation
• ARP request frame construction and arpreq
• ARP reply polling and stats
• IPv4 + ICMP echo request frame construction
• ICMP echo reply polling and stats

Phase 8: AI Integration

• COM2 UART plumbing and detection
• COM2 LLM proxy line protocol commands: aistatus, aiask, aipoll
• Host-side COM2 proxy bridge validation
• External command-backed host bridge
• OpenAI Responses API host bridge adapter

Phase 9: TCP/IP Stack (complete)

• TCP/IP stack design document: docs/spec/DESIGN-TCPIP.md
• Shared network types, configuration, endian helpers, and checksum helpers in net.zig
• Ethernet frame send/receive dispatch layer and netpoll
• ARP cache table with pending/resolved entries and legacy arpreq compatibility
• IPv4 send/receive/routing layer and ICMP migration onto IPv4
• UDP datagram send/receive path
• Shell commands: ifconfig, netpoll, arp, udpsend, tcpconnect, tcpsend, tcprecv, tcpclose, tcpstat, dns, httpget
• TCP connection state machine with connect/send/recv/close
• DNS A-record client over UDP
• Socket-like API for future shell/userland integration

Phase 10: User Mode (complete)

• User mode design document: docs/spec/DESIGN-USERMODE.md
• Syscall infrastructure: int 0x80 dispatch, SYS_WRITE, SYS_GETPID, SYS_EXIT teardown, syscall stats
• syscallstat shell command for dispatcher stats
• User address space management in user_mem.zig
• usermemtest shell command verifies user page mapping and CR3 restore
• User process loading and context switching via process.zig, user_programs.zig, task.zig, and scheduler.zig
• Built-in hello_user flat program runs through Ring 3, SYS_WRITE, and SYS_EXIT
• Shell integration: runuser hello and user/process details in ps
• Process lifecycle syscall: SYS_YIELD
• Built-in loop_user flat program runs through Ring 3, SYS_WRITE, and SYS_YIELD
• Scheduling smoke test: runuser loop, shell preemption, and live killuser
• ELF parser/load helper in elf.zig with elftest segment/load smoke check
• ELF-backed user process execution from VFS with /bin/hello.elf and runelf
• Process lifecycle syscall: SYS_SLEEP with blocked-task wakeups
• Process lifecycle syscall: SYS_BRK with heap page mapping
• Process lifecycle syscall: SYS_READ with foreground keyboard stdin
• Full Phase 10 user-mode regression after SYS_READ
• Shell integration: killuser
• Protection tests: bad_cli and bad_read
• Multi-user-process preemption with runuser pair

Phase 11: Userland File ABI (complete)

• Userland file syscall roadmap/spec updates
• Per-process VFS file descriptor table
• Process lifecycle syscall: SYS_OPEN
• Process lifecycle syscall: SYS_CLOSE
• Process lifecycle syscall: SYS_STAT
• File-backed SYS_READ for user fd >= 3
• Built-in file_user flat program and runuser file shell integration
• Phase 11 QEMU regression after file syscalls
• Process lifecycle syscall: SYS_MMAP
• Built-in mmap_user flat program and runuser mmap shell integration

Zig vs Rust: Why Rewrite?

Feature	Zig Approach	Rust Approach
GDT/IDT	comptime — zero runtime cost	Lazy (runtime init)
Allocator	Explicit, per-call	Global #[global_allocator]
Error handling	Error unions (unified)	Mix of Option/Result/panic
Inline asm	Stable, first-class	Requires nightly features
C interop	Native @cImport	FFI + unsafe blocks
Dependencies	Zero — all from scratch	x86_64, spin, pic8259, etc.

Documentation

• Design and implementation plan
• User mode implementation spec
• Contributor guide
• Agent workflow notes

License

MIT