m3OS Docs | Phases

Boot Foundation

Boot the kernel through UEFI, print useful output over serial, and halt cleanly. This is the first end-to-end proof that the workspace, toolchain, boot path, and panic path all work together.

Memory Basics

Move from a static early kernel into a kernel that can allocate memory safely and reason about physical and virtual address space.

Interrupts

Handle exceptions and hardware interrupts reliably enough to support timing, keyboard input, and basic fault diagnosis.

Tasking

Introduce multiple concurrent execution contexts in the kernel and make timer-driven preemption visible and understandable.

Userspace Entry

Run the first ring 3 program and prove that privilege separation, page permissions, and basic syscalls work.

IPC Core

Turn the kernel into a real microkernel by making userspace services communicate through explicit message passing and capabilities.

Core Servers

Use IPC to assemble the first useful userspace services and prove that the system can be structured as cooperating servers rather than one large kernel.

Storage And VFS

Expose files through userspace services so programs can read named resources instead of relying on embedded data or ad hoc kernel hooks.

Framebuffer And Shell

Make the OS pleasant to interact with by adding on-screen text output and a very small shell for manual exploration.

Secure Boot

Sign the kernel's EFI binary so it can boot on real hardware with UEFI Secure Boot enabled, without needing to disable the firmware security check.

Process Model

Load and execute arbitrary userspace binaries from disk as isolated ring-3 processes, with a proper lifecycle: spawn, run, wait, exit.

POSIX Compat

Implement enough Linux-compatible syscalls and bundle musl libc so that ordinary C programs compiled on the host can run unmodified inside the OS.

Allow processes to create, write, and delete files so the OS has persistent and ephemeral mutable storage. A RAM-backed tmpfs provides scratch space; FAT32 gains write support for persistence across reboots.

Shell And Tools

Turn the minimal shell from Phase 9 into a genuinely useful interactive environment: pipes, I/O redirection, job control, environment variables, and a small set of core utilities that exercise the filesystem and process model.

Hardware Discovery

Replace the hardcoded, single-core interrupt model with proper hardware discovery via ACPI and PCI, and switch from the legacy 8259 PIC to the APIC. This unlocks multi-core support and arbitrary device discovery in later phases.

Network

Add a minimal but real TCP/IP stack so the OS can send and receive packets over a network. A virtio-net NIC in QEMU is the hardware target. The end goal is a working `ping` and a simple TCP connection.

Memory Reclamation

Close the memory leaks that have accumulated since Phase 2. The bump frame allocator is replaced with a free-list allocator that can actually reclaim frames, the kernel heap grows on demand instead of being fixed at 1 MiB, kernel stacks are freed when processes exit, and `fork` switches from eager full-copy to copy-on-write so parent and child share physical pages until one of them writes.

Directory VFS

Make the filesystem navigable. Right now `getdents64` returns ENOSYS, directories cannot be opened as file descriptors, every process thinks its working directory is `/`, and the ramdisk is a flat array with no directory hierarchy. This phase fixes all of that: directories become first-class objects, paths resolve relative to a real per-process working directory, and the ramdisk gains a tree structure so binaries live under `/bin` instead of floating in a flat namespace.

Signal Handlers

Enable userspace programs to install and execute signal handlers. Implement the signal trampoline mechanism so ring-3 code can catch `SIGINT`, `SIGSEGV`, `SIGCHLD`, and other signals, run a user-supplied handler, and return cleanly to the interrupted execution without kernel assistance beyond the initial delivery and the `sigreturn` syscall.

Userspace Init Shell

Replace the kernel-resident `init_task` and `shell_task` ring-0 functions with real ring-3 userspace processes. After this phase PID 1 is a `no_std` Rust binary loaded from the ramdisk; the interactive shell is a userspace ELF that init spawns. The kernel is no longer responsible for parsing commands or managing the interactive session.

Ion Shell

Replace the minimal `no_std` shell from Phase 20 with [ion](https://github.com/redox-os/ion) -- the shell built for Redox OS, another custom Rust OS. After this phase `/bin/ion` is the interactive shell that userspace init spawns. The kernel-level and custom-shell scaffolding from Phase 20 remains as a regression harness; the user-facing shell gains a real scripting language, job control, pipelines, and interactive line editing (the latter pending Phase 22 TTY).

ANSI Escape

Learn how ANSI Escape fits into m3OS.

TTY PTY

Give userspace programs a real terminal abstraction. The kernel's raw stdin buffer and hardcoded `stdin_feeder_task` are replaced by a proper TTY layer with a configurable line discipline. Programs can switch between cooked and raw mode via `tcgetattr` / `tcsetattr`, query the window size via `TIOCGWINSZ`, and detect whether they are attached to a terminal via `isatty`. The phase also lays the infrastructure for a future PTY master/slave pair.

Socket API

Expose the kernel's existing TCP/IP stack to userspace via standard Linux socket syscalls. At the end of this phase a userspace program can open a TCP connection, send an HTTP/1.0 request, and receive the response — entirely from ring-3 code, with no kernel modifications needed for each new network program. The `ping` shell builtin moves out of the kernel and into a standalone userspace ELF.

Persistent Storage

Give m3OS a persistent block device so that files written during one boot session survive into the next. A virtio-blk driver (the simplest PCI virtio device in QEMU) handles raw sector I/O; a partition parser finds the FAT32 data partition; the existing `fat_server` gains a write path that flushes directly to disk. After this phase, writing a file to `/data` and rebooting leaves the file visible on the next boot (and on the host via `losetup` or similar).

SMP

Boot all available CPU cores, give each its own Local APIC timer, and run the scheduler across all cores simultaneously. Two processes should be able to execute truly in parallel.

Text Editor

A usable text editor runs inside the OS. Users can create, edit, and save files from the shell. This is the foundational tool that makes all subsequent "do real work inside the OS" phases possible — you cannot write code, configuration files, or documents without an editor.

User Accounts

The OS supports multiple user accounts with login authentication, file ownership, and permission enforcement. A `login` program prompts for username and password before granting shell access. This is the foundation for multi-user operation and secure remote access.

Ext2 Filesystem

Replace FAT32 as the primary persistent filesystem with ext2, which natively stores Unix ownership (uid/gid), permission modes, and timestamps in every inode. After this phase, file permissions set via `chmod`/`chown` survive reboots and the FAT32 permissions index file workaround from Phase 27 is no longer needed.

PTY Subsystem

Implement real pseudo-terminal (PTY) pairs so that multiple independent terminal sessions can run simultaneously. A PTY master/slave pair connects a terminal emulator (or network server) to a shell process, enabling remote access (telnet, SSH) and local terminal multiplexing.

Telnet Server

A telnet server runs inside the OS, allowing remote users to log in over the network and get an interactive shell session. This is the first demonstration of the OS as a networked, multi-user system — a machine you can connect to from another computer (or another terminal on the host) and do real work.

Compiler Bootstrap

Run a C compiler natively inside the OS. A C source file written at the shell prompt (using the editor from Phase 26) can be compiled and executed without leaving the OS. The ultimate target is self-hosting: the compiler compiles itself.

Build Tools

Multi-file C projects can be built inside the OS using a `make`-compatible build tool and shell scripts. This transforms the OS from a "compile one file" environment into one where real software projects can be developed.

Kernel Memory Improvements

The kernel heap allocator is robust, efficient, and recoverable. Out-of-memory conditions no longer panic the kernel — the allocator grows on demand and retries failed allocations. Buddy allocation, working `munmap()`, userspace-heap coalescing, and slab-cache infrastructure all land. Broad migration of hot kernel object families onto slab caches remains later work.

Real Time Clock

The OS knows what time it is. A CMOS RTC driver reads the hardware clock at boot to establish the current wall-clock time. `clock_gettime(CLOCK_REALTIME)` returns actual Unix timestamps, distinct from `CLOCK_MONOTONIC` which tracks time since boot. The `date` command displays the current date and time.

True SMP Multitasking

All CPU cores dispatch and run user tasks. The BSP-only restriction is removed by making syscall infrastructure per-core. The scheduler introduces per-CPU run queues with load balancing and task priorities, substantially improving dispatch locality and multi-core throughput even though the global scheduler lock remains on the dispatch hot path for task-state coordination.

Expanded Memory

The kernel supports demand paging, large `mmap()` regions, and `mprotect()`. Virtual pages are mapped lazily — physical frames are allocated on first access via the page fault handler. This unlocks running large cross-compiled binaries (Clang, Python, Node.js, git) that allocate hundreds of megabytes via `mmap()` but only touch a fraction of the mapped pages. QEMU RAM is increased to support these workloads.

I/O Multiplexing

Programs can wait on multiple file descriptors simultaneously without busy-waiting. `select()`, an improved `poll()`, and `epoll` provide scalable I/O readiness notification. Non-blocking I/O (`O_NONBLOCK`) works for sockets, pipes, and PTYs. Event-driven servers become possible.

Filesystem Enhancements

The filesystem supports symlinks, hard links, `umask`-backed creation defaults, the remaining Unix permission semantics needed for symlink-aware metadata and directory listing, a `/proc` filesystem for process introspection, and basic device nodes (`/dev/null`, `/dev/zero`, `/dev/urandom`, `/dev/full`). These are the filesystem primitives that Unix tools and build systems assume exist.

Unix Domain Sockets

The OS supports `AF_UNIX` (Unix domain) sockets for high-performance local inter-process communication. Programs can create stream and datagram sockets bound to filesystem paths. `socketpair()` creates connected pairs for parent-child IPC after `fork()`. This is the primary IPC mechanism on Linux, used by D-Bus, X11, systemd, PostgreSQL, Docker, and many other systems.

Threading Primitives

The OS supports kernel-level threads via `clone()` with `CLONE_THREAD` and `CLONE_VM`. Multiple threads share an address space and can synchronize via `futex()`. Thread-local storage works via `arch_prctl(ARCH_SET_FS)`. This enables multi-threaded C programs and improves musl libc compatibility (which uses threads internally even for single-threaded programs).

Expanded Coreutils

The OS ships with a comprehensive set of Unix utilities sufficient for daily development work. Moving beyond the minimal set from Phase 14, this phase adds text processing, file inspection, and system administration tools that developers expect.

Async Executor

Learn how Async Executor fits into m3OS.

Crypto Primitives

The OS has a cryptography library providing hash functions, symmetric encryption, and asymmetric key operations. This is the foundation layer that SSH (Phase 43) and future security features build upon.

Crash Diagnostics

Every kernel crash is self-diagnosing. When the kernel panics or takes a fatal fault, the serial output includes full CPU register state, current task metadata, and per-core scheduler context. `debug_assert!` invariants at every scheduler, fork, IPC, and stack boundary catch state corruption at the point of origin rather than surfacing later as an opaque `RIP=0x4` fault.

Kernel Trace Ring

Every kernel crash includes a structured timeline of recent scheduler, fork, and IPC events. The per-core lockless trace ring records events with timestamps, and the auto-dump on panic/fault merges all cores into a single sorted timeline in the serial output. The ring is host-testable, accessible from userspace, and feature-gated for zero-cost release builds.

Regression Stress Ci

A layered test infrastructure that catches SMP race conditions through focused QEMU regression tests, looped stress tests with automatic artifact capture, seed-based iteration for reproducibility (guest-side timing variation deferred), host-side property and concurrency testing for extracted scheduler/fork/IPC models, and CI tier mapping that runs regressions on every PR and stress tests nightly.

SSH Server

An SSH server runs inside the OS, providing encrypted remote shell access. Users can connect from any standard SSH client (`ssh user@host`) with password or public key authentication. This replaces the telnet server for untrusted networks and is a major milestone: the OS is now a secure, networked, multi-user system.

Rust Cross Compilation

Rust programs compiled on the host run natively inside the OS. A documented toolchain setup enables writing Rust code on the host, cross-compiling to an x86-64 ELF binary linked against musl, and deploying it to the OS's disk image. Stretch goal: a minimal Rust program compiles inside the OS itself.

Ports System

A simple BSD-style ports system enables building and installing third-party software inside the OS from source recipes. A port is a directory containing a Makefile, patches, and a Portfile that automates extracting, compiling, and installing a piece of software. At least 5 ports build and install successfully, with dependency resolution.

System Services

The OS has a service manager, system logging, and scheduled task execution. Services (sshd, telnetd, etc.) are managed by a unified init/service system that handles startup ordering, restart on failure, and clean shutdown. The OS behaves like a real server that can be administered remotely.

Doom

m3OS can run DOOM as a real full-screen graphical application. The game loads its WAD data from disk, renders through the framebuffer path, accepts keyboard input for gameplay, and returns the system to a usable administration path when it exits.

Security Foundation

m3OS closes the trust-floor gaps that currently block any honest claim of "safe enough for serious headless use." When this phase lands, identity transitions, password storage, entropy, and default remote-exposure behavior all match the project's intended multi-user and network-facing story.

Architectural Declaration

m3OS gains an explicit, enforceable architecture contract for what belongs in ring 0, what is transitional, and what must move to userspace over time. The phase also turns the giant syscall surface into a structure that can be unwound safely in later phases.

IPC Completion

m3OS gains the missing IPC and bulk-data pieces required for serious userspace services: safe capability transfer, practical large-payload transport, ring-3-safe service registration, and clear failure semantics for the canonical server loop.

Service Model Maturity

m3OS turns its new service-management baseline into a reliable lifecycle model: boot ordering is explicit, restart semantics are trustworthy, shutdown behavior is deterministic, logs are coherent, and extracted ring-3 services can plug into the same operator workflow instead of inventing their own.

First Service Extractions

m3OS proves that its microkernel direction is real by extracting at least the first visible core services out of the kernel address space. Console and input-related functionality become supervised ring-3 services, and the system demonstrates that they can fail and be restarted without rebooting the machine.

Kernel Architecture Evolution

Phase 52c established the architecture direction for per-core scheduling, growable IPC resources, a unified kernel-side line discipline, O(log n) VMA lookup, and ISR wakeup improvements. In the checked-in tree, the VMA tree, growable endpoint/capability/service tables, `LineDiscipline`, the live `push_raw_input` keyboard path, and the ISR wake queue all landed. Phase 52d then recorded the remaining honest limits: the scheduler hot path still relies on the global `SCHEDULER` lock, and notifications remain fixed-size for ISR safety.

Kernel Completion And Roadmap Alignment

The Phase 52 follow-on work now matches reality: the roadmap truthfully describes what landed, syscall return state is task-owned end-to-end, keyboard input uses the kernel line discipline instead of a ring-3 clone, the integrated boot/login path survives the former `rt_sigaction` stall, generated initrd payloads no longer dirty the source tree, and the smoke/regression gates for login, fork, ion, and PTY flows are trustworthy again.

Kernel Reliability Fixes

All four confirmed kernel bugs from the Phase 52 bug investigations are fixed, with targeted regression tests proving each fix.

Kernel Structural Hardening

The kernel's memory management, context management, and TLB coherence subsystems move onto the structurally hardened path defined by this phase. In the checked-in tree, the AddressSpace object, typed user buffers, batched TLB work, and frame zeroing landed, and Phase 52d completed the remaining closure work so the task-owned return-state and generation-tracking story now matches the shipped implementation end to end.

Headless Hardening

m3OS becomes a deliberately operable headless/reference system: the security floor is repaired, the service model is trustworthy, the basic developer workflow is boringly repeatable, and the project has explicit validation gates for what it now claims to support.

Kernel Memory Modernization

The kernel memory subsystem becomes SMP-scalable and auditable: per-CPU page caching removes the global frame-allocator lock from the common single-page path, a magazine-based slab allocator with out-of-line slab metadata replaces the linked-list heap for small kernel objects, and the allocator preserves Phase 52b's zero-before-user-exposure guarantee while eliminating the double-lock and O(n) buddy removal paths.

Deep Serverization

m3OS moves beyond proof-of-concept extraction and pushes real storage, namespace, and networking responsibilities out of the kernel. The kernel becomes a thinner object and transport layer, while userspace services own more of the policy-heavy behavior that currently dominates the trusted computing base.

Post Serverization Kernel Hygiene

Close the `FdEntry` CLOEXEC / NONBLOCK plumbing gap and relocate the four `arch::x86_64::syscall::*_pub` wrappers into their owning subsystems so later phases do not inherit a silent security bug or a process-module arch dependency.

Hardware Substrate

m3OS supports a small, deliberate reference-hardware matrix with a documented driver strategy, a reusable hardware-access layer, and at least one serious real-hardware storage and networking path. The project stops talking about hardware support as a vague future aspiration and starts treating it as a bounded support promise.

Display And Input Architecture

m3OS gains a real display and input model: one userspace-owned display service controls presentation, keyboard and mouse events are routed through an explicit focus-aware protocol, and multiple graphical clients can coexist without raw framebuffer conflicts.

Audio And Local Session

m3OS supports a minimal local interactive session that feels like a system rather than a demo: there is a defined graphical session entry path, a basic terminal or launcher workflow, and audible PCM output on the supported platform.

Release 1 0 Gate

m3OS defines and validates what "1.0" actually means. The phase produces an explicit support matrix, release gates, non-goals, and documentation commitments for either a headless/reference 1.0 or a broader local-system milestone if the optional graphical branch is ready.

Browse the implementation roadmap