Genesis

CustomOS 1.0.0 - a from-scratch, higher-half x86_64 operating system. Kernel, drivers, networking, graphics, USB, audio, and a freestanding userland that boots into an interactive shell and a software-rendered desktop.

See ABOUT.md for a full project overview.

What is CustomOS?

CustomOS is a complete educational operating system written from scratch for the x86_64 architecture. It is booted by the Limine bootloader into a freestanding, higher-half C17 kernel that brings up eight major subsystems and lands at an interactive userland shell, with a software-rendered graphical desktop when a framebuffer is present.

The project is deliberately built breadth-first: rather than perfecting a single component, it demonstrates a coherent, layered path all the way from firmware to a running Ring 3 program. Every layer depends only on the layers below it, no subsystem reaches around a boundary (for example, only the boot-info module ever touches Limine, and only ACPI parses firmware tables), and the whole system can be validated in a single boot.

Highlights of the design philosophy:

Freestanding. The kernel and the userland both link against a project-owned C library, never a host libc, host OS headers, or third-party runtimes.
Higher-half. The kernel executes in the upper canonical address space and owns its own page tables immediately after early bring-up.
One subsystem per file with strict bottom-up layering and documented ownership rules.
No SSE anywhere. The kernel never enables the FPU/SSE; every zeroing and copy path is integer code, verified by disassembly.
Provable at a glance. A single MASTER_SELFTEST build runs every subsystem self-test plus a deterministic stress harness and prints one consolidated PASS/FAIL report (26 of 26 on q35).

Release 1.0.0 is codenamed "Genesis". The version lives in exactly one place, kernel/include/version.h, and is surfaced in both the boot banner and the consolidated boot report.

Feature Highlights

Limine boot protocol consumed behind a single immutable bootinfo_* API.
Physical memory manager, four-level paging VMM with guard pages, a boundary-tag kernel heap, and a slab allocator.
ACPI discovery (RSDP/RSDT/XSDT, FADT/MADT/HPET/MCFG) and a modern interrupt path (LAPIC, IOAPIC, HPET, calibrated LAPIC timer) with a legacy PIC/PIT fallback.
Preemptive round-robin scheduler with threads, context switching, IRQ-safe spinlocks, sleeping mutexes, wait queues, and a sleep queue.
Per-process address spaces, a static ELF64 loader, Ring 3 execution via iretq, an INT 0x80 syscall ABI, and validated user copies.
A reference-counted Virtual File System with a RAMFS root, GPT partitions, a read-mostly FAT32 driver, and a write-through block cache over AHCI SATA DMA.
A generic device/driver model with a conflict-checking resource manager and a brute-force PCI enumerator (BAR sizing, MSI/MSI-X/PCIe capability walk).
A full TCP/IP stack (e1000/RTL8139, Ethernet/ARP/IPv4/ICMP/UDP/TCP, loopback, DHCP) and a BSD-style socket API driving ping, ifconfig, and netstat.
A software graphics stack: double-buffered framebuffer, drawing primitives, a bitmap font, a PS/2 mouse cursor, a kernel window manager/compositor, widgets, a desktop shell, and a userland windowing API (gui_demo).
A USB stack: xHCI host controller, enumeration/addressing, external hubs, boot-protocol HID keyboard/mouse, and Bulk-Only mass storage as a block device.
An audio stack: Intel HD Audio (Azalia) controller, CORB/RIRB verbs, codec and widget-graph enumeration, BDL/PCM DMA playback, a mixer, and a play WAV tool.
A freestanding userland: libc, crt0, init (PID 1), a cooked TTY, an interactive shell, and coreutils, packaged onto a FAT32 disk image.

Capability Matrix

Status legend: Done = implemented and self-tested; Partial = implemented within a documented, deliberate scope (see Known Limitations).

Core kernel

Subsystem	Status	Highlights	Deep dive
Boot info	Done	Immutable `bootinfo_*` over all Limine responses; normalized memory map.	BOOTINFO.md
Diagnostics	Done	`panic`/`panicf`, `KASSERT`/`KVERIFY`, CPUID report, full boot report.	DIAGNOSTICS.md
Timekeeping	Done	Pluggable tick/counter (HPET, LAPIC timer, PIT priority).	TIMEKEEPING.md
Input	Done	Lock-free SPSC event queues; PS/2 and USB HID backends.	INPUT.md
PMM	Done	Page-frame database + bitmap; double/invalid-free detection.	MEMORY.md
VMM	Done	Four-level paging, per-section permissions, HHDM, guard pages.	VMM.md
Heap / slab	Done	Boundary-tag segregated free list; slab caches.	HEAP.md
ACPI	Done	RSDP/RSDT/XSDT + FADT/MADT/HPET/MCFG, checksum-validated.	ACPI.md
Interrupts / timers	Done	LAPIC + IOAPIC + HPET + LAPIC timer; PIC/PIT fallback.	APIC.md
Scheduler	Done	Preemptive round-robin, spinlocks/mutexes/wait queues, sleep.	SCHEDULER.md
Processes	Done	Address spaces, ELF64 loader, Ring 3 via `iretq`.	PROCESS.md
Syscalls	Done	40-call `INT 0x80` ABI, validated usercopy.	SYSCALL.md

Storage, devices, and I/O

Subsystem	Status	Highlights	Deep dive
VFS	Done	Inode/superblock/mount/path, RAMFS root, descriptor tables.	VFS.md
Block / GPT	Done	LBA block devices; CRC-validated GPT partitions.	VFS.md
FAT32	Partial	Read-mostly on-disk driver (8.3 + long names).	PERSISTENT_STORAGE.md
Block cache	Done	Hash + LRU, write-through.	PERSISTENT_STORAGE.md
AHCI SATA	Done	48-bit DMA read/write; disks as `sataN`.	PERSISTENT_STORAGE.md
NVMe	Partial	Controller bring-up scaffold (no data path yet).	DEVICE.md
Device / PCI	Done	Registry, resource manager, PCI BAR/MSI/PCIe scan.	DEVICE.md

Connectivity and multimedia

Subsystem	Status	Highlights	Deep dive
NIC drivers	Done	e1000 (8086:100E) and RTL8139 (10EC:8139).	NETWORKING.md
TCP/IP	Partial	Ethernet/ARP/IPv4/ICMP/UDP/TCP; no fragmentation, minimal congestion control.	NETWORKING.md
Sockets / DHCP	Done	BSD socket API + syscalls; DHCP client with static fallback.	NETWORKING.md
Graphics	Partial	Software-only compositor/desktop; single 32bpp display.	GRAPHICS.md
USB	Partial	xHCI only; boot-protocol HID + Bulk-Only mass storage.	USB.md
Audio	Partial	Intel HD Audio only, playback only, 16-bit 44.1/48 kHz.	AUDIO.md
Userland	Done	libc, `init`, cooked TTY, shell, coreutils.	USERLAND.md

Top-Level Architecture

CustomOS is a monolithic, freestanding, higher-half kernel. Responsibilities are partitioned by directory and layered strictly bottom-up: each layer uses only the layers beneath it, and lower layers reach higher ones exclusively through registered function-pointer hooks (for example, the timer drives the scheduler through a tick hook, never by including scheduler.h).

graph TD
    subgraph FW["Firmware and boot"]
        UEFI["UEFI / BIOS firmware"]
        LIM["Limine 8.6.1"]
        START["_start (arch/x86_64)"]
        BI["bootinfo (owns all Limine responses)"]
    end
    subgraph ARCH["Arch / CPU"]
        CPU["GDT / TSS / IDT / ISR / CPUID"]
    end
    subgraph MM["Memory"]
        PMM["PMM (page frames)"]
        VMM["VMM (four-level paging)"]
        HEAP["Heap + slab"]
    end
    subgraph PLAT["Platform"]
        ACPI["ACPI discovery"]
        APIC["LAPIC / IOAPIC / HPET / LAPIC timer"]
    end
    subgraph SCHED["Scheduling"]
        THR["Threads + scheduler"]
        SYNC["Spinlock / mutex / wait queue / sleep"]
    end
    subgraph PROC["Process and syscalls"]
        AS["Address spaces + ELF loader"]
        SYS["INT 0x80 syscall ABI + usercopy"]
    end
    subgraph IO["Storage and devices"]
        VFS["VFS / RAMFS / FAT32 / bcache"]
        DEV["Device model + PCI"]
        DRV["Drivers: AHCI / e1000 / RTL8139 / xHCI / HDA"]
    end
    subgraph HL["High-level subsystems"]
        NET["Networking stack"]
        GFX["Graphics compositor"]
        USB["USB core"]
        AUD["Audio core"]
    end
    USER["Userland: init, shell, coreutils, tools"]

    UEFI --> LIM --> START --> BI
    BI --> CPU --> PMM --> VMM --> HEAP
    HEAP --> ACPI --> APIC --> THR --> SYNC
    THR --> AS --> SYS
    SYS --> VFS
    APIC --> DEV --> DRV
    DRV --> VFS
    DRV --> NET
    DRV --> USB
    DRV --> AUD
    VFS --> GFX
    SYS --> NET
    SYS --> GFX
    SYS --> AUD
    NET --> USER
    GFX --> USER
    VFS --> USER

See docs/README.md for the full design, ownership rules, and the higher-half memory layout.

Boot Sequence

kmain brings the system up in a fixed, dependency-respecting order. The flow below mirrors docs/BOOT_SEQUENCE.md.

flowchart TD
    A["Firmware: UEFI or BIOS"] --> B["Limine 8.6.1 loads kernel ELF"]
    B --> C["_start: verify base revision"]
    C --> D["serial_init"]
    D --> E["bootinfo_initialize (validate Limine responses)"]
    E --> F["memory_map_initialize (read-only topology)"]
    F --> G["pmm_initialize (frame allocator)"]
    G --> H["cpu_init: GDT / TSS / IDT / PIC / PIT / PS2 kbd + mouse"]
    H --> I["vmm_initialize (build kernel PML4, switch CR3)"]
    I --> J["heap_initialize (kmalloc / slab online)"]
    J --> K["acpi_initialize (enumerate + checksum tables)"]
    K --> L["interrupt_controller_initialize (APIC backend or PIC fallback)"]
    L --> M["net_early_initialize + audio_initialize (register cores)"]
    M --> N["device_manager_initialize (PCI scan + driver bind)"]
    N --> O["scheduler_initialize + scheduler_start"]
    O --> P["process_initialize + syscall_initialize"]
    P --> Q["storage_initialize (VFS + RAMFS + FAT32 mount)"]
    Q --> R["net_initialize + usb_hid_start_service + tty_initialize"]
    R --> S["userland_populate_root + desktop_initialize"]
    S --> T["diagnostics_print_all (boot report)"]
    T --> U["process_run_initial (Ring 3 demo)"]
    U --> V{"MASTER_SELFTEST?"}
    V -- yes --> W["master_selftest_run (26/26 report)"]
    V -- no --> X["userland_start_init: exec /bin/init as PID 1"]
    W --> X
    X --> Y["Interactive shell + desktop, then cpu_halt idle"]

Subsystem Overview

Each subsystem below has a one-paragraph summary, a diagram where it clarifies the design, and a link to its deep-dive document.

Boot, Diagnostics, Time, Input

The boot-information subsystem is the single owner of every Limine response (memory map, HHDM, kernel address, framebuffer, RSDP, modules, command line, boot time); no other module touches Limine. Diagnostics provide panic/panicf, KASSERT/KVERIFY, CPUID feature reporting, and the consolidated boot report. Timekeeping exposes a hardware-independent time_* API backed by a pluggable tick source (HPET, then the LAPIC timer, then the PIT). Input is a lock-free single-producer/single-consumer event model with PS/2 and USB HID backends.

Deep dives: BOOTINFO.md, DIAGNOSTICS.md, TIMEKEEPING.md, INPUT.md.

Memory Management

Memory ownership flows strictly upward: boot info normalizes the Limine map, a read-only discovery pass analyzes topology, the PMM hands out physical frames, the VMM owns page tables and address spaces, and the heap serves byte-granular allocations that are backed by VMM-mapped frames. Nothing below the heap depends on it.

graph LR
    BI["bootinfo (normalized map)"] --> DISC["memory discovery (read-only)"]
    DISC --> PMM["PMM: physical frames"]
    PMM --> VMM["VMM: page tables / address spaces"]
    VMM --> HEAP["kmalloc / kfree"]
    HEAP --> SLAB["slab caches"]
    VMM --> MMIO["vmm_map_mmio (device registers)"]

Deep dives: MEMORY_TOPOLOGY.md, MEMORY.md, VMM.md, HEAP.md.

Platform: ACPI and APIC

ACPI is the sole owner of firmware-table parsing: it validates the RSDP and RSDT/XSDT root, checksum-validates every table, and decodes the FADT, MADT, HPET, and MCFG (discovery only, no hardware programmed). The interrupt controller then consumes that topology to software-enable the Local APIC (the sole EOI authority), initialize the I/O APIC(s) honoring MADT overrides, enable the HPET, and calibrate and start the LAPIC timer as the system tick. The legacy PIC/PIT are retained as an automatic fallback.

Deep dives: ACPI.md, APIC.md.

Threads and Scheduling

A preemptive round-robin scheduler runs on the timer tick. Threads own guard-page-protected kernel stacks; the context switch saves the full register set on each thread's own stack. The actual switch happens on the interrupt-return path after EOI, so it can never wedge the interrupt controller. Synchronization provides IRQ-safe spinlocks, sleeping mutexes, wait queues, and a sleep queue.

stateDiagram-v2
    [*] --> CREATED : thread_create
    CREATED --> READY
    READY --> RUNNING : schedule
    RUNNING --> READY : yield / preempt
    RUNNING --> SLEEPING : thread_sleep
    RUNNING --> BLOCKED : mutex / wait_queue
    SLEEPING --> READY : wake_tick
    BLOCKED --> READY : wake
    RUNNING --> TERMINATED : thread_exit
    TERMINATED --> [*] : join / destroy

Deep dive: SCHEDULER.md.

Processes, User Mode, and Syscalls

Each process owns a private address space (a fresh PML4 whose higher half is shared with the kernel). A static ELF64 loader maps PT_LOAD segments with exact permissions, and the process drops to Ring 3 via iretq. System calls use a DPL-3 INT 0x80 gate; all user pointers cross the boundary through validated copy_to/from_user helpers.

Deep dives: PROCESS.md, SYSCALL.md.

Storage: VFS and Filesystems

The VFS models inodes, superblocks, and filesystem types with reference counting; RAMFS is the writable root and FAT32 mounts read-only at /mnt. Below the VFS, a write-through block cache sits over LBA block devices, and GPT partitions expose each entry as a child device. AHCI provides real SATA DMA block I/O.

graph TD
    SYS["syscalls: open/read/write/..."] --> FD["descriptor table"]
    FD --> FILE["struct file"]
    FILE --> VFS["VFS: inode / superblock"]
    VFS --> RAMFS["RAMFS (root)"]
    VFS --> FAT32["FAT32 (/mnt, read-mostly)"]
    FAT32 --> BC["block cache"]
    BC --> BDEV["block device"]
    PART["GPT partition"] --> BDEV
    AHCI["AHCI SATA DMA"] --> BDEV

Deep dives: VFS.md, PERSISTENT_STORAGE.md.

Devices and PCI

A generic device model, a driver framework with a match/probe/attach/detach binding loop, and a conflict-checking resource manager sit under a brute-force PCI enumerator that sizes every BAR, walks the capability list (MSI/MSI-X/PCIe), reserves resources, and publishes each function as a device. Drivers for AHCI, NVMe, e1000, RTL8139, xHCI, and Intel HD Audio bind into this framework.

Deep dive: DEVICE.md.

Networking

The stack is serialized by one global lock, with heavy work in a dedicated netd thread. It provides Ethernet/ARP/IPv4/ICMP/UDP/TCP, a loopback device, a DHCP client, and a BSD-style socket API where each socket is a struct file.

stateDiagram-v2
    [*] --> CLOSED
    CLOSED --> SYN_SENT : connect
    CLOSED --> LISTEN : listen
    LISTEN --> SYN_RCVD : recv SYN
    SYN_SENT --> ESTABLISHED : recv SYN-ACK
    SYN_RCVD --> ESTABLISHED : recv ACK
    ESTABLISHED --> FIN_WAIT_1 : close
    ESTABLISHED --> CLOSE_WAIT : recv FIN
    FIN_WAIT_1 --> FIN_WAIT_2 : recv ACK
    FIN_WAIT_2 --> TIME_WAIT : recv FIN
    CLOSE_WAIT --> LAST_ACK : close
    LAST_ACK --> CLOSED : recv ACK
    TIME_WAIT --> CLOSED : timeout

Deep dive: NETWORKING.md.

Graphics

The window manager and compositor run in the kernel and expose a userland client API via SYS_GFX_* syscalls. Rendering is software-only into a PMM-backed back buffer that is presented to the Limine framebuffer in one pass.

graph LR
    APP["userland: gui_demo"] -->|SYS_GFX_*| COMP["compositor"]
    KWIN["kernel widgets / desktop"] --> COMP
    MOUSE["PS/2 + USB mouse"] --> COMP
    COMP --> BACK["double buffer (PMM)"]
    BACK --> FB["Limine framebuffer"]

Deep dive: GRAPHICS.md.

USB

A host-controller-independent core drives a single xHCI HCD. Enumeration is one state machine used for both root-hub and hub-downstream devices; class drivers bind HID keyboards/mice into the input path and Bulk-Only mass storage into the block layer.

sequenceDiagram
    participant HCD as xHCI HCD
    participant CORE as USB core
    participant DEV as Device
    participant DRV as Class driver
    HCD->>CORE: root-hub port connected
    CORE->>DEV: port reset -> speed
    CORE->>DEV: Enable Slot + Address Device
    CORE->>DEV: GET_DESCRIPTOR (device, config)
    CORE->>DEV: SET_CONFIGURATION
    CORE->>DRV: match + probe
    DRV->>DEV: class requests (HID / SCSI)

Deep dive: USB.md.

Audio

A hardware-independent audio core sits over an Intel HD Audio (Azalia) driver that maps MMIO, resets the controller, runs CORB/RIRB verb exchange, enumerates the codec and widget graph, discovers and unmutes a DAC-to-pin output path, and streams 16-bit PCM through a BDL cyclic buffer driven by the position register.

graph LR
    PLAY["play (WAV)"] -->|SYS_AUDIO_*| CORE["audio core (cyclic buffer)"]
    CORE --> HDA["Intel HDA driver"]
    HDA --> CORB["CORB / RIRB verbs"]
    HDA --> BDL["BDL + stream descriptor"]
    BDL --> DAC["codec DAC -> pin"]

Deep dive: AUDIO.md.

Userland

The userland is freestanding: programs link against the project's own libc and crt0, are static non-PIE ET_EXEC images, and are packaged onto the FAT32 disk under /bin. init runs as PID 1 and supervises an interactive shell over a cooked TTY line discipline, with coreutils and network/graphics/audio tools.

Deep dive: USERLAND.md.

Quick Start: Build and Run

CustomOS builds on a POSIX shell (Linux, macOS, WSL2, or MSYS2 on Windows). The kernel is always compiled with the project-local x86_64-elf cross toolchain, never the host compiler.

Prerequisites

A project-local x86_64-elf cross toolchain (built by make toolchain).
Host tools: make, nasm, xorriso, mtools, qemu-system-x86_64, and optionally gdb.
python3 (used by scripts/mkdisk.py to build the disk image).

Windows / MSYS2 PATH setup

On Windows, run the commands from an MSYS2 shell, or prepend the MSYS2 tool directories to PATH first. PowerShell does not support &&, so run each command on its own line.

$env:PATH = "C:\msys64\mingw64\bin;C:\msys64\usr\bin;$env:PATH"

Build and boot

make toolchain          # once: provision the local x86_64-elf toolchain
make limine             # once: fetch/build Limine 8.6.1 into third_party/limine
make                    # build kernel.elf and the hybrid BIOS/UEFI ISO (same as: make iso)
make user               # build the freestanding userland (init, shell, coreutils, tools)
make disk               # build the GPT + FAT32 disk image with userland /bin
make run-disk           # boot the ISO in QEMU (q35) with the SATA disk + e1000 NIC -> shell

Other useful targets:

make run                # boot the ISO only (no disk)
make run-usb            # boot with an xHCI controller + usb-kbd/mouse/storage stick
make run-audio          # boot with the disk + an Intel HD Audio output codec
make debug              # boot QEMU paused with a GDB stub on tcp::1234
make rebuild            # clean + iso
make print-config       # show the resolved toolchain and flags

Whole-system validation (single boot)

make run-disk MASTER_SELFTEST=1

This compiles in every non-destructive subsystem self-test plus the deterministic stress harness and prints one consolidated PASS/FAIL boot report (26/26 on q35). For full-device coverage, attach the USB and audio device sets as well:

make run-disk MASTER_SELFTEST=1 \
  QEMU_USB_FLAGS="-device qemu-xhci,id=xhci -device usb-kbd,bus=xhci.0 -device usb-mouse,bus=xhci.0 -drive if=none,id=usbstk,file=build/customos-usb.img,format=raw -device usb-storage,bus=xhci.0,drive=usbstk" \
  QEMU_AUDIO_FLAGS="-audiodev none,id=snd0 -device intel-hda -device hda-output,audiodev=snd0"

QEMU device flags (from the Makefile)

Purpose	Flags
Base machine	`-M q35 -m 512M -serial stdio -no-reboot -no-shutdown`
ISO boot	`-cdrom build/customos.iso -boot order=d`
SATA disk	`-drive id=customosdisk,file=build/customos-disk.img,format=raw,if=none -device ich9-ahci,id=ahci -device ide-hd,drive=customosdisk,bus=ahci.0`
Networking	`-netdev user,id=n0 -device e1000,netdev=n0` (override `NIC_MODEL=rtl8139`)
USB	`-device qemu-xhci,id=xhci -device usb-kbd,bus=xhci.0 -device usb-mouse,bus=xhci.0 -drive if=none,id=usbstk,file=build/customos-usb.img,format=raw -device usb-storage,bus=xhci.0,drive=usbstk`
Audio	`-audiodev wav,id=snd0,path=build/out.wav -device intel-hda -device hda-output,audiodev=snd0`

Full details, every self-test switch, and the debug workflow are in docs/BUILD.md.

Repository Layout

CustomOS/
  README.md               This document
  docs/README.md          Documentation index
  Makefile                Build pipeline (kernel + userland + ISO + disk + QEMU)
  boot/                   Limine configuration (limine.cfg)
  kernel/                 Freestanding higher-half kernel
    arch/x86_64/          Entry, GDT/TSS/IDT/ISR, syscall + context asm, linker.ld
    kernel/               Portable services: bootinfo, time, input, tty, userland
    mm/                   Memory: memory_map, pmm, paging, vmm, heap, slab
    platform/             ACPI tables + LAPIC/IOAPIC/HPET/APIC timer + controller
    sched/               Threads, scheduler, spinlock, mutex, wait_queue, sleep
    process/              Address spaces, ELF loader, usercopy, syscall, process
    fs/                   block_device, partition, vfs, ramfs, mount, path, file,
                          descriptor, bcache, fat32
    device/               resource, device, driver, pci, device_manager
    drivers/              serial, pic, pit, ps2_keyboard, ps2_mouse, ahci, nvme,
                          e1000, rtl8139
    net/                  net core, ethernet, arp, ipv4, icmp, udp, tcp, socket,
                          loopback, dhcp, net_selftest
    gfx/                  gfx, font, compositor, widget, desktop, gfx_selftest
    usb/                  usb core, xhci, usb_hid, usb_storage, usb_hub, selftest
    audio/                audio core, hda, audio_selftest
    lib/                  log, panic, assert, stress, master_selftest, diagnostics
    include/              Public kernel headers (kernel.h, version.h, limine.h, ...)
  user/                   Freestanding userland
    lib/                  libc + crt0
    include/              userland headers (ABI-matched to the kernel)
    bin/                  init, sh, coreutils, ping/ifconfig/netstat, gui_demo, play
    user.ld               Userland linker script
  scripts/                toolchain, fetch-limine, build/run/debug, mkdisk.py
  third_party/limine/     Vendored Limine 8.6.1 (not modified)
  toolchain/              Project-local x86_64-elf cross compiler
  docs/                   Documentation set (this set) and docs/images/
  build/                  Out-of-tree artifacts (gitignored)

Testing and Self-Tests

Every subsystem ships a hermetic self-test compiled in with a build switch (make iso <NAME>_SELFTEST=1). Two aggregate switches drive release validation: STRESS=1 adds the deterministic stress harness, and MASTER_SELFTEST=1 runs every non-destructive self-test plus the stress harness in a single boot and prints one consolidated report.

Switch	Covers
`BOOTINFO_SELFTEST`	Centralized Limine data, accessor consistency, memory-map sanity.
`MEMORY_MAP_SELFTEST`	Topology totals, region ordering/alignment, classification.
`PMM_SELFTEST`	Single/multi/aligned allocation, free, double/invalid-free, OOM.
`VMM_SELFTEST`	Map/unmap/translate/protect, TLB, guard pages, no leaks.
`HEAP_SELFTEST`	kmalloc/kcalloc/krealloc, alignment, growth, coalescing, slab.
`ACPI_SELFTEST`	RSDP/root + per-table checksums, MADT/HPET/FADT/MCFG parsing.
`APIC_SELFTEST`	LAPIC access/EOI, LAPIC-timer calibration, IOAPIC routing, HPET.
`SCHEDULER_SELFTEST`	Thread switching, fairness, mutex/spinlock, wait/sleep, preemption.
`PROCESS_SELFTEST`	ELF validation, address spaces, Ring 3, syscall, usercopy.
`VFS_SELFTEST`	Block I/O, GPT, RAMFS, path traversal, mounts, descriptors.
`PERSIST_SELFTEST`	Block-cache miss/hit, write-through, invalidation.
`DEVICE_SELFTEST`	Device registry, resource conflicts, driver binding, BAR decode.
`USERLAND_SELFTEST`	exec-from-disk with argv, spawn/wait, coreutils, rejection.
`NET_SELFTEST`	Checksums, UDP, full TCP session, ICMP over loopback.
`GFX_SELFTEST`	Primitives, clipping, blits, alpha, font, composite ordering.
`USB_SELFTEST`	xHCI bring-up, enumeration, HID binding, mass-storage read.
`AUDIO_SELFTEST`	Controller reset, CORB/RIRB, codec/path, BDL, position advance.
`STRESS`	Heap/PMM/thread/FS/cache/net/graphics churn, leak-checked.
`MASTER_SELFTEST`	All of the above (implies `STRESS`); one PASS/FAIL report.

The fault-injection probes (EXCEPTION_SELFTEST, IRQ_SELFTEST, PANIC_SELFTEST, ASSERT_SELFTEST) halt the machine on purpose and are excluded from the master run; run them individually. See docs/BUILD.md.

Screenshots

These images are placeholders except for the desktop capture. Replace them with real captures per docs/images/IMAGE_MANIFEST.md.

Software desktop	Interactive shell

gui_demo client window	MASTER_SELFTEST boot report

Roadmap and Known Limitations

CustomOS 1.0.0 is breadth-first by design. Every subsystem has a deliberate, documented scope (for example, xHCI-only USB, playback-only Intel HD Audio, no IP fragmentation, minimal TCP congestion control, software-only graphics, read-mostly FAT32, and no SMP or fork yet).

Known Limitations: honest, per-subsystem scope.
Future Roadmap: near/mid/long-term direction.
Release Notes 1.0.0: headline features and what is new.

Documentation Index

The complete, grouped documentation index lives in docs/README.md. Quick links:

Getting started: BUILD.md, TOOLCHAIN.md, BOOT_SEQUENCE.md
Core: BOOTINFO.md, MEMORY.md, VMM.md, HEAP.md, ACPI.md, APIC.md, SCHEDULER.md, PROCESS.md, SYSCALL.md
Subsystems: VFS.md, PERSISTENT_STORAGE.md, DEVICE.md, NETWORKING.md, GRAPHICS.md, USB.md, AUDIO.md, USERLAND.md
Reference and release: API_REFERENCE.md, RELEASE_NOTES_1_0.md, KNOWN_LIMITATIONS.md, FUTURE_ROADMAP.md

License

CustomOS is released under the MIT License. The vendored Limine bootloader under third_party/limine/ retains its own upstream license.

Name		Name	Last commit message	Last commit date
boot		boot
build		build
docs		docs
kernel		kernel
scripts		scripts
third_party		third_party
toolchain		toolchain
user		user
.gitattributes		.gitattributes
.gitignore		.gitignore
ABOUT.md		ABOUT.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation