Strat9 OS

An experimental operating system kernel written in Rust, targeting x86_64 (primary) and aarch64 (secondary).

Quick start

# Build the full OS image (bootloader + kernel)
cargo make build-all

# Run in QEMU
cargo make run-gui

# Run with SMP (multi-core)
cargo make run-gui-smp

Architecture guides

API reference by category

Core

The kernel, ABI definitions, and bootloader : the foundation of the OS.

Syscall & Userspace

Userspace libraries for interacting with the kernel.

Component Framework

Trait-based component model for drivers and services.

Network Drivers

Intel Ethernet and NIC queue management.

Filesystem

Filesystem abstraction and implementations.

Networking

Network stack, silo network service, and tools.

System Services

Admin interfaces, compatibility layers, and experimental features.

Testing

Building docs locally

# Build the full docs site (mdBook + rustdoc)
bash tools/scripts/build-docs-site.sh

# Serve locally
python3 -m http.server --directory build/docs-site 8000

# Check for broken links
python3 tools/scripts/check-links.py --site-dir build/docs-site

Architecture Overview

Strat9 OS is a microkernel-inspired operating system written in Rust. The kernel runs in Ring 0 on x86_64, with userspace processes isolated through capability-based security and silo boundaries.

Kernel subsystems

graph TB
    subgraph "Ring 0 : Kernel"
        BOOT[Boot / Init]
        SCHED[Scheduler]
        MEM[Memory Manager]
        IPC[IPC]
        CAP[Capability System]
        SILO[Silo Manager]
        VFS[VFS]
        SYSCALL[Syscall Entry]
        HW[Hardware Drivers]
    end

    subgraph "Ring 3 : Userspace"
        INIT[Init Process]
        APP[Applications]
        SVC[Services]
    end

    BOOT --> SCHED
    BOOT --> MEM
    SYSCALL --> SCHED
    SYSCALL --> MEM
    SYSCALL --> IPC
    SYSCALL --> CAP
    SYSCALL --> VFS
    SCHED --> MEM
    IPC --> MEM
    IPC --> CAP
    SILO --> CAP
    SILO --> MEM
    VFS --> MEM
    HW --> SYSCALL

    APP --> SYSCALL
    SVC --> SYSCALL
    INIT --> SYSCALL
    SILO -.-> APP
    SILO -.-> SVC

Subsystem summary

Design principles

1. Capability-based security : All kernel resources (memory, IPC ports, devices) are accessed through unforgeable CapId tokens. No raw pointers leak to userspace.

2. Silo isolation : Processes run inside silos (analogous to containers). Each silo has memory quotas, capability boundaries, and IPC restrictions. Policy lives in userspace; the kernel enforces mechanisms.

3. Per-CPU scheduling : Each CPU core has its own run queue set. Tasks are pinned to cores via the scheduler, avoiding cross-core lock contention on the hot path.

4. COW-first memory : fork() shares pages via copy-on-write. Physical frames are freed only when the last reference disappears. Buddy allocator provides O(1) order-0 allocations via per-CPU caches.

5. Scheme-based I/O : Filesystem operations go through a VFS layer that routes to scheme handlers (like Plan 9). Userspace can implement custom schemes for devices, networks, and IPC.

Data flow: userspace syscall

sequenceDiagram
    participant U as Userspace
    participant K as Syscall Entry
    participant C as Capability Check
    participant S as Subsystem

    U->>K: syscall(SYS_READ, fd, buf, len)
    K->>K: Validate args, disable IRQs
    K->>C: Resolve CapId from fd
    C->>C: Check permissions (read)
    C->>S: Dispatch to VFS read
    S->>S: Page fault / buffer I/O
    S-->>K: Return bytes read
    K-->>U: Result in RAX

Silo System

Silos are Strat9 OS's primary isolation mechanism. Each silo is a container for processes with bounded resources, restricted capabilities, and filesystem access control. Policy lives in userspace; the kernel enforces mechanisms.

Overview

graph TB
    subgraph "Admin (Silo Admin)"
        ADMIN[Console Admin / Web Admin]
    end

    subgraph "Kernel"
        SM[Silo Manager]
        CAP[Capability System]
        MEM[Memory Accounting]
        EV[Event Queue]
    end

    subgraph "Silo 1 (System)"
        T1[Task A]
        T2[Task B]
    end

    subgraph "Silo 2 (User)"
        T3[Task C]
    end

    ADMIN -->|create/config/start/stop| SM
    SM --> CAP
    SM --> MEM
    SM --> EV
    T1 --> CAP
    T2 --> CAP
    T3 --> CAP
    T1 -.-> MEM
    T3 -.-> MEM

Silo identity

Each silo has a numeric ID (SiloId) and a tier derived from the ID range:

User-tier silos cannot have hardware or control permissions (enforced at creation).

Silo lifecycle

stateDiagram-v2
    [*] --> Created : SYS_SILO_CREATE
    Created --> Ready : SYS_SILO_CONFIG + SYS_SILO_ATTACH_MODULE
    Ready --> Running : SYS_SILO_START
    Running --> Paused : SYS_SILO_SUSPEND
    Paused --> Running : SYS_SILO_RESUME
    Running --> Stopping : SYS_SILO_STOP (graceful)
    Stopping --> Stopped : tasks exit
    Running --> Stopped : SYS_SILO_KILL (force)
    Stopped --> [*] : SYS_SILO_DESTROY
    Running --> Crashed : fault / panic
    Crashed --> Stopped : cleanup

States: Created → Loading → Ready → Running → Paused → Stopping → Stopped → Destroyed (also Crashed, Zombie)

Resource limits

The SiloConfig struct defines per-silo resource bounds:

SiloConfig {
    mem_min: u64,           // Minimum guaranteed memory (bytes)
    mem_max: u64,           // Maximum allowed memory (0 = unlimited)
    cpu_shares: u32,        // CPU share weight (for proportional scheduling)
    cpu_quota_us: u64,      // CPU time quota per period (microseconds)
    cpu_period_us: u64,     // Quota period (microseconds)
    cpu_affinity_mask: u64, // CPU affinity bitmask
    max_tasks: u32,         // Maximum concurrent tasks
    io_bw_read: u64,        // Read bandwidth limit
    io_bw_write: u64,       // Write bandwidth limit
    flags: u64,             // Feature flags
    family: u8,             // Silo family (SYS/DRV/FS/NET/WASM/USR)
}

Memory accounting: Every allocation through the kernel heap charges against the silo's mem_usage_bytes. When mem_max is exceeded, charge_current_task_memory() returns OutOfMemory. This is enforced transparently in the buddy allocator and slab paths.

Octal mode (pledge/unveil)

Access control uses an OctalMode with three permission groups, encoded as a 12-bit octal value:

Example: 0o755 = LIST+STOP+SPAWN + INTERRUPT+IO + LOOKUP+BIND

Pledge

SYS_SILO_PLEDGE(mode) restricts the silo's permissions. The new mode must be a subset of the current mode : escalation is rejected with PermissionDenied.

silo.mode.pledge(new_mode):
    if !new_mode.is_subset_of(self.mode):
        return PermissionDenied  // escalation attempt
    self.mode = new_mode

Unveil

SYS_SILO_UNVEIL(path, rights) restricts filesystem access to specific paths with read/write/execute permissions. Multiple rules can be added; if a path matches no rule, access is denied.

Rights bits: read (0x1), write (0x2), execute (0x4)

Matching: A rule /srv/data matches /srv/data/file.txt but not /srv/other. Rule / matches everything.

Enter Sandbox

SYS_SILO_ENTER_SANDBOX() is irreversible : it clears all registry permissions and prevents further capability grants. Once sandboxed, the silo cannot escape.

Family types

Feature flags

Module system (CMOD)

Silos can load code modules in the CMOD binary format:

Strat9ModuleHeader {
    magic: "CMOD",
    version: 1 or 2,
    cpu_arch: 0 (x86_64),
    flags: MODULE_FLAG_SIGNED | MODULE_FLAG_KERNEL,
    code_offset/size, data_offset/size, bss_size,
    entry_point,
    export/import/relocation tables,
    key_id, signature,
    cpu_features_required (v2+),
}

Loading flow:

1. Admin calls SYS_MODULE_LOAD with a blob (from file, IPC stream, or initfs path)
2. Kernel validates the header (magic, version, alignment, signature)
3. Module is registered in the global ModuleRegistry
4. Admin calls SYS_SILO_ATTACH_MODULE to bind the module to a silo
5. Admin calls SYS_SILO_START to launch the silo's entry point

Events

The kernel pushes events to a fixed-capacity ring buffer (256 entries). Userspace polls via SYS_SILO_EVENT_NEXT.

Crash encoding: data0 = fault_reason | (subcode << 16)

• PageFault (1), GeneralProtection (2), InvalidOpcode (3)

Silo admin

Admin operations require a ResourceType::Silo capability with grant permission. The SILO_ADMIN_RESOURCE (resource 0) is the special admin handle.

Bootstrap: The init process receives a silo-admin capability at boot via create_silo_admin_capability().

Admin operations:

Path-based label assignment

When a filesystem path matches /srv/strate-fs-<type>/<label>/, the label is automatically assigned to the silo. This allows convention-based service discovery.

Silo vs. other isolation mechanisms

Memory Management

Strat9 OS uses a layered memory architecture: physical frame allocation (buddy), kernel heap (slab), virtual memory (page tables + COW), and large-object allocation (vmalloc).

Memory hierarchy

graph TB
    subgraph "Physical"
        BUDDY[Buddy Allocator]
        ZONES[Zone DMA / Normal / HighMem]
        FRAMES[Physical Frames 4KiB]
    end

    subgraph "Kernel Heap"
        SLAB[Slab Sub-allocator]
        HEAP[GlobalAlloc Heap]
    end

    subgraph "Virtual Memory"
        AS[Address Space / PML4]
        VMA[Virtual Memory Regions]
        COW[COW Pages]
        PAGING[Page Tables]
    end

    subgraph "Large Objects"
        VMALLOC[Vmalloc]
    end

    BUDDY --> FRAMES
    ZONES --> BUDDY
    FRAMES --> SLAB
    SLAB --> HEAP
    FRAMES --> PAGING
    AS --> VMA
    VMA --> COW
    COW --> PAGING
    FRAMES --> VMALLOC

Buddy allocator

The buddy allocator manages physical frames. It divides memory into zones (DMA, Normal, HighMem) and uses a free-list per order (0–10) for power-of-two allocations.

Key properties:

• Order-0 allocations go through per-CPU caches (LOCAL_FRAME_CACHES) for O(1) fast path
• Cross-CPU stealing when local cache is empty
• Compaction assist when high-order allocations fail
• Refcount sentinel: free-list frames carry REFCOUNT_UNUSED (u32::MAX)

alloc order-0:
  1. Try local cache (per-CPU, PreemptDisabled lock)
  2. Refill cache from buddy global
  3. Steal from other CPU caches
  4. Fallback to global buddy allocator

Slab heap

The kernel heap uses a slab sub-allocator for small objects (≤ 2048 bytes). Each size class has its own free list backed by whole pages from the buddy allocator.

Allocations > 2048 bytes go directly to the buddy allocator via vmalloc.

Copy-on-Write (COW)

COW enables efficient fork() by sharing physical frames between parent and child.

sequenceDiagram
    participant P as Parent
    participant K as Kernel
    participant C as Child

    P->>K: fork()
    K->>K: Clone page tables (mark all RO + COW)
    K->>K: Share physical frames (refcount++)
    K-->>C: New address space

    Note over C: Child writes to shared page
    C->>K: Page fault (COW)
    K->>K: Allocate new frame, copy page
    K->>K: Remap child's PTE (RW, clear COW)
    K->>K: Decrement parent refcount
    K-->>C: Write succeeds

COW refcount invariant:

• refcount == 1 → sole owner (no sharing)
• refcount > 1 → shared (writes trigger COW fault)
• refcount == REFCOUNT_UNUSED → free-list frame

Page tables

The kernel uses x86_64 4-level paging (PML4 → PDPT → PD → PT).

Address space layout:

• PML4[0..256] → user space (per-process)
• PML4[256..512] → kernel space (shared across all processes)

Each user process gets a fresh PML4 with the kernel half cloned from the boot PML4. This shares kernel L3/L2/L1 subtrees : kernel mapping changes propagate automatically.

Vmalloc

Large non-contiguous allocations use vmalloc, which maps arbitrary physical pages into a contiguous virtual range. Used for:

• Large metadata arrays
• Buffers that don't need physical contiguity
• Allocations > buddy max order

Boot Sequence

Strat9 OS boots on x86_64 via the Limine boot protocol. The boot flow transitions from 16-bit real mode through protected mode to 64-bit long mode before jumping into Rust.

Boot flow

flowchart TD
    A[BIOS/UEFI] --> B[MBR / Stage 1]
    B --> C[Stage 2]
    C --> D[Limine Protocol]
    D --> E[kstart - Assembly]
    E --> F[start - Rust init]
    F --> G[main.rs - Kernel main]

    style A fill:#333,color:#fff
    style D fill:#1a6b3a,color:#fff
    style G fill:#1a6b3a,color:#fff

Stage 1 : MBR bootloader (bootloader/asm/)

The bootloader is written in NASM assembly. Stage 1 fits in exactly 512 bytes (MBR).

Responsibilities:

1. Load Stage 2 from disk (LBA reads via BIOS INT 13h)
2. Enable A20 line
3. Enter protected mode (32-bit)
4. Jump to Stage 2

Stage 2 : Protected → Long mode

Responsibilities:

1. Detect available memory (INT 15h, E820)
2. Load the kernel binary from disk
3. Set up initial page tables (identity mapping + higher-half)
4. Enable PAE, PGE, long mode
5. Jump to 64-bit code

Limine handoff

The kernel is loaded by the Limine bootloader protocol. Limine provides:

• Memory map (E820 equivalent)
• HHDM (Higher Half Direct Map) base address
• PML4 physical address
• RSDP (ACPI tables)
• Framebuffer info

The KernelArgs struct captures all handoff data:

KernelArgs {
    hhdm_offset: u64,       // Higher-half direct map base
    pml4_physical: u64,     // Boot page table
    acpi_rsdp: Option<NonNull<u8>>,  // ACPI RSDP
    memory_regions: &[MemoryRegion],  // E820 memory map
    framebuffer: FramebufferInfo,     // VGA/framebuffer
}

Kernel entry : kstart (assembly)

Located in boot/boot64.S:

1. Verify BSS is zero, data is non-zero (sanity check)
2. Set up kernel stack (128 KiB, from STACK static)
3. Jump to start() (Rust)

Kernel init : start() (Rust)

Located in boot/limine.rs → main.rs:

flowchart TD
    A[serial::init] --> B[gdt::init_bsp]
    B --> C[idt::init_bsp]
    C --> D[memory::init]
    D --> E[paging::init]
    E --> F[interrupt::syscall::init]
    F --> G[allocator::init - buddy + slab]
    G --> H[acpi::init - parse MADT/IOAPIC]
    H --> I[apic::init - Local APIC]
    I --> J[smp::init - boot APs]
    J --> K[timer::init - APIC timer]
    K --> L[process::init - scheduler]
    L --> M[shell::init - init process]
    M --> N[scheduler::run - never returns]

Key init steps:

SMP boot : Application Processors

sequenceDiagram
    participant BSP
    participant TRAMP as Trampoline (0x8000)
    participant AP

    BSP->>TRAMP: Copy trampoline to 0x8000
    BSP->>TRAMP: Write CR3 + RSP to data area
    BSP->>AP: INIT IPI (0x4500)
    Note right of AP: 16-bit real mode
    BSP->>AP: SIPI (vector=0x8 → 0x8000)
    TRAMP->>AP: Enable protected mode
    TRAMP->>AP: Enable long mode + paging
    TRAMP->>AP: Load kernel stack
    TRAMP->>AP: Jump to smp_main (Rust)
    AP->>BSP: BOOTED_CORES++
    BSP->>BSP: Wait for all APs
    BSP->>AP: Open scheduler gate
    AP->>AP: Start per-CPU scheduler

IPC Mechanisms

Strat9 OS provides a 3-level hybrid IPC transport model with a central Transport Manager that selects the appropriate isolation level per silo pair. Each level offers a different trade-off between performance and isolation.

IPC Architecture Overview

graph TB
    subgraph "Transport Manager"
        TM[Decision Matrix<br/>Tier × Tier → Level]
    end

    subgraph "N1 : TypeSafe IPC"
        N1[IntrusiveMailbox<br/>Ring 0, approx. 3-10 cycles<br/>Rust type isolation]
    end

    subgraph "N2 : Lock-Free Ring"
        N2[LockFreeRing<br/>Ring 3, approx. 400-4000 cycles<br/>SPSC + futex notification]
    end

    subgraph "N3 : MMU Thread Migration"
        N3[MmuEndpoint<br/>Ring 3, approx. 800-2000 cycles<br/>CR3 switch + PCID]
    end

    TM --> N1
    TM --> N2
    TM --> N3

Transport selection matrix

N1 : Type-Safe IPC (IntrusiveMailbox)

The fastest transport : kernel-internal, same address space, approx. 3-10 cycles per message.

How it works

Two kernel components (e.g., scheduler ↔ VFS) communicate via an intrusive LIFO mailbox. Messages are linked directly in kernel memory using tagged pointers (x86-64 ABA-safe). No copy, no lock, no syscall.

Constraints

• Ring 0 only : both sender and receiver must be kernel components
• 100% Rust Safe : #[forbid(unsafe_code)] required, cargo-geiger = 0
• LIFO ordering : not FIFO; use N2 if ordering matters
• No untrusted input : forbidden for network, user data, external files

Usage

let mailbox = IntrusiveMailbox::new();
mailbox.push(b"notification")?;  // approx. 3 cycles
let msg = mailbox.pop();          // LIFO: last message first

N2 : Lock-Free Ring (SPSC)

High-throughput shared-memory transport : approx. 400-4000 cycles depending on sleep mode.

How it works

A lock-free SPSC ring buffer backed by physically contiguous DMA-accessible pages. The producer writes data, sets a Release barrier on len, then publishes via tail.store(Release). The consumer observes tail, reads data via Acquire, and advances head. Futex notification for sleeping consumers.

Two sub-modes

Memory layout

Page 0: RingHeader (cache-line padded)
  Line 0: magic, capacity, slot_size, flags, notify_seq
  Line 1: head (consumer hot)  : 60B padding
  Line 2: tail (producer hot)  : 60B padding
Pages 1+: RingSlot entries
  Each: [len:u16][flags:u16][data:u8; SLOT_SIZE]

Usage

let (producer, consumer) = create_spsc_pair(256);  // 256 slots

// Producer (kernel or Ring 3)
producer.write(b"packet data")?;
producer.notify_consumer();  // futex wake

// Consumer (strate-net, Ring 3)
let mut buf = [0u8; 2048];
let n = consumer.read(&mut buf)?;

NIC integration (data plane)

NIC HW Queue 0 → Ring SPSC 0 → strate-net (poll round-robin)
NIC HW Queue 1 → Ring SPSC 1 →
NIC HW Queue 2 → Ring SPSC 2 →

Each RSS queue gets its own SPSC ring : no MPSC contention, no head-of-line blocking.

N3 : MMU Thread Migration (Research Track)

Maximum isolation : approx. 800-2000 cycles : currently research track with N2 fallback.

How it works

Inspired by L4 Thread Migration (Liedtke 1995): instead of a full syscall + context switch, the kernel migrates the CPU quantum directly to the target process by switching CR3 (address space) and jumping to the handler. Three tiers:

Status

⚠️ Research track : N3 is not yet implemented. All User↔User pairs fall back to N2 (LockFree Ring).

Legacy mechanisms (still available)

These mechanisms predate the Transport Manager and remain functional:

IPC Ports (synchronous message-passing)

Typed MPMC Channels

let (tx, rx) = channel::<MyMessage>(64);
tx.send(msg)?;           // blocks if full
let msg = rx.recv()?;    // blocks if empty

Shared Ring (legacy)

High-throughput bulk IPC using shared-memory ring buffers. Superseded by N2 Lock-Free Ring for new code.

Semaphore

POSIX-like counting semaphore for synchronization.

Transport Manager API

Creating a transport

let manager = TransportManager::new();
let result = manager.establish(
    src_silo, dst_silo,
    TransportConfig {
        min_level: TransportLevel::LockFree,
        ring_capacity: Some(256),
        slot_size: None,
    },
)?;
// result.local and result.remote are the endpoints

Dynamic policy override

// Force N2 for a specific silo pair
manager.set_policy(src_sid, dst_sid, TransportLevel::LockFree, 512);

Syscall interface (planned)

Performance comparison

References

1. Xu, P. & Roscoe, T. (2025) : The NIC should be part of the OS, HotOS'25 : arXiv
2. Liedtke, J. (1995) : On µ-Kernel Construction, SOSP
3. Hunt, G.C. & Larus, J.R. (2007) : Singularity: Rethinking the Software Stack, ACM Queue
4. Levy, A. et al. (2017) : Multiprogramming a 64kB Computer Safely and Efficiently with Tock, SOSP
5. Vyukov, D. : Bounded MPMC queue : lock-free SPSC/MPMC benchmarks
6. Axboe, J. (2019) : Efficient IO with io_uring, kernel.org

IPC Transport Architecture

Driver Model

Strat9 OS uses a trait-based component model for drivers. Each driver registers itself during boot and is discovered through PCI/VirtIO enumeration.

Driver categories

graph TB
    subgraph "Storage"
        NVMe[NVMe]
        AHCI[AHCI/SATA]
        VIO_BLK[VirtIO Block]
    end

    subgraph "Network"
        E1000[E1000/E1000e]
        IGC[IGC]
        VIO_NET[VirtIO Net]
    end

    subgraph "Input"
        USB_HID[USB HID]
        PS2[PS/2 Keyboard]
    end

    subgraph "Display"
        FB[Framebuffer]
        VGA[VGA text mode]
    end

    subgraph "Bus"
        PCI[PCI enumeration]
        VIO[VirtIO transport]
        USB[XHCI host controller]
    end

    PCI --> NVMe
    PCI --> AHCI
    PCI --> E1000
    PCI --> IGC
    VIO --> VIO_BLK
    VIO --> VIO_NET
    USB --> USB_HID

Component trait

All drivers implement the Component trait, which provides a uniform registration interface:

pub trait Component: Send + Sync {
    fn name(&self) -> &str;
    fn init(&self) -> Result<(), ComponentError>;
    fn shutdown(&self);
}

Components are registered at boot via the component-macro derive macro:

#[derive(Component)]
struct MyDriver { /* ... */ }

PCI enumeration

The PCI bus is scanned at boot using a BFS algorithm with early-exit optimization:

1. For each (bus, device), probe function 0 first
2. If vendor == 0xFFFF → skip all 8 functions (early exit)
3. Read header type bit 7 for multi-function flag
4. If PCI-to-PCI bridge → enqueue secondary bus

This reduces worst-case probes from 65,536 to approx. 8,192 for typical topologies.

Key PCI types:

NIC drivers

E1000 / E1000e

Intel Ethernet drivers supporting:

• Legacy descriptor rings (T/R)
• MSI-X interrupt moderation
• Multicast filter
• VLAN offload

IGC

Intel I225/I226 2.5GbE driver with:

• Advanced RX/TX descriptors
• Time-based interrupt coalescing
• Hardware timestamping

Common NIC infrastructure

Storage drivers

NVMe

Full NVMe driver with:

• I/O queues (per-CPU submission/completion pairs)
• MSI-X interrupt steering
• Namespace management
• Admin queue for controller commands

AHCI / SATA

AHCI controller driver for SATA devices:

• Port enumeration
• DMA PRDT (Physical Region Descriptor Table)
• FIS-based communication

VirtIO Block

Paravirtualized block device for QEMU/KVM:

• VirtIO queue negotiation
• Multi-queue support
• Feature bits (discard, write cache)

USB stack

graph TD
    XHCI[XHCI Host Controller] --> HUB[Hub Driver]
    HUB --> HID[USB HID - Keyboard/Mouse]
    HUB --> MASS[USB Mass Storage]
    HUB --> NET[USB Ethernet]

The XHCI driver manages the USB host controller, enumerates devices through hub traversal, and dispatches to class-specific drivers (HID, mass storage, etc.).

VirtIO transport

VirtIO provides paravirtualized device access for QEMU/KVM:

Device discovery flow

sequenceDiagram
    participant BOOT as Boot
    participant PCI as PCI Scanner
    participant DRV as Driver Registry
    participant DEV as Device

    BOOT->>PCI: Scan PCI bus
    PCI->>DRV: Notify: device found
    DRV->>DRV: Match vendor/device ID
    DRV->>DEV: Initialize driver
    DEV->>DEV: Map BARs, enable bus mastering
    DEV->>DEV: Register IRQ handler
    DEV-->>BOOT: Device ready

ABI Overview

The canonical ABI definitions live in workspace/abi (strat9-abi crate).

Focus modules:

• strat9_abi::syscall for syscall numbers
• strat9_abi::data for shared wire/data structs
• strat9_abi::flag for ABI-level flags
• strat9_abi::errno for error codes
• strat9_abi::boot for boot handoff ABI

API reference:

• strat9_abi::syscall
• strat9_abi::data
• strat9_abi::flag
• strat9_abi::errno
• strat9_abi::boot

ABI Changelog

This page tracks ABI evolution for strat9-abi.

Versioning policy

• Major (ABI_VERSION_MAJOR) changes only for incompatible wire/layout changes.
• Minor (ABI_VERSION_MINOR) changes for backward-compatible additions.
• No silent renumbering of existing syscall IDs.
• repr(C) and explicit size checks are mandatory for exported ABI structs.

Current version

• ABI_VERSION_MAJOR = 0
• ABI_VERSION_MINOR = 1
• Packed: 0.1

See:

• crate root constants
• syscall numbers
• ABI data structs

Recent ABI updates (auto-generated)

• 2026-06-25 4fb871f Refactor error codes and syscall flags; implement getrandom syscall
• 2026-06-25 a522fb8 Refactor NIC data plane and IPC transport statistics
• 2026-06-25 d1e838f feat: implement IPC transport layer with 3-level architecture
• 2026-06-25 411f5aa feat: add IPC transport layer support and enhance ICMP handling
• 2026-06-25 5a3d69c feat: migrate input system to userspace
• 2026-06-24 3fea3f3 SMP hardware debug, NVMe fixes, VGA refactor, telnetd hardening, docs
• 2026-06-16 e4ab1a9 Enhance network stack, NIC drivers, USB/NVMe subsystems, and thermal management
• 2026-06-03 0c40058 Refactor the network stack and add dual-stack userspace tooling
• 2026-05-24 aeade5e Code cleanup
• 2026-05-24 b2bbcc0 Improve and fix IPC
• 2026-05-23 db23b53 Fix major memory leak and remove sshd silo
• 2026-05-19 93c8927 async: implement and optimize async I/O completion handling
• 2026-05-18 7c5efb4 async: io_uring-like async I/O — ring, dispatch, AHCI bridge (Phases 1-4)
• 2026-05-14 cc4944a Refactor and clean up code in various modules
• 2026-05-14 ecc416d refactor: strate-init refactoring, ELF/VFS/signal hardening, TSC calibration fix
• 2026-05-08 f070d41 Add kernel entropy pool with interrupt-driven collection
• 2026-05-08 9dedb9f Implement robust list support (set_robust_list/get_robust_list)
• 2026-05-08 d2e90a2 Bridge clone() thread creation via SYS_THREAD_CREATE, add faccessat routing
• 2026-05-08 dabcad2 Add sys_access(), sys_faccessat(), and SYS_GETRANDOM() in syscall dispatcher
• 2026-05-08 946f200 Add missing call for clock_nanosleep and update the calling manager
• 2026-05-06 117863e Enhance network and silo management functionality
• 2026-04-12 6963e28 fix: reduce scheduler contention and harden early boot memory init
• 2026-04-12 f3647c1 feat(memory): production-grade allocator architecture (#49)
• 2026-04-06 a941264 feat: capability-based CWD, *at syscalls, and O_RESOLVE_BENEATH sandboxing
• 2026-04-06 309a9c1 refactor: runtime allocation, scheduler lock decoupling, FixedQueue, and VGA improvements
• 2026-03-26 a9a6cd6 Implement block-oriented memory management and ownership tracking
• 2026-03-23 ec8ee9f refactor(memory): update reference counting logic for COW frames
• 2026-03-23 aaa89e0 Refactor: Decouple per-CPU scheduler state and logic from the global scheduler instance by moving SchedulerCpu to local CPU storage.
• 2026-03-21 c3f93c6 feat: Implement TSC-based boot timing and milestones, along with an analysis...
• 2026-03-17 eb7818d feat: Implement static module loading from initfs paths and increase module blob size limit.

Changelog entries

0.1

• Introduced canonical strat9-abi crate as single source of truth.
• Unified syscall numbers in strat9_abi::syscall.
• Unified shared structs (TimeSpec, IpcMessage, FileStat, PCI types).
• Added boot handoff ABI (KernelArgs, MemoryRegion, MemoryKind) with magic/version checks.
• Added ABI introspection syscall SYS_ABI_VERSION.

Entry template

Use this template for future ABI entries:

### X.Y
- Added:
  - <new syscalls/types/flags>
- Changed (compatible):
  - <field additions, new constants, optional semantics>
- Changed (breaking):
  - <layout/numbering/semantic breaks>
- Migration notes:
  - <what userspace/kernel must update>

ABI Support Matrix

Status of musl platform APIs on x86_64-unknown-strat9.

Legend: OK = implemented, Stub = returns ENOSYS, Partial = limited.

POSIX File I/O

Process Management

Signals

Network / Sockets

Epoll

Syscall Reference

Complete reference for all Strat9 OS syscalls. Syscalls are invoked via the syscall instruction (x86_64). Arguments are passed in registers; the return value is in RAX.

ABI convention: Success returns a non-negative value. Errors return a negative errno value (two's complement). Userspace checks if result > 0xFFFF_F000 to detect errors, then applies !result + 1 to get the errno number.

Constants

AT_* flags (for *at syscalls)

Open flags

Protection flags (mmap)

Signal constants

Waitpid options

Clock IDs

Handle operations

Errors: EBADF (invalid handle), EPERM (no grant permission), ESRCH (target process not found)

Memory management

Prot flags: PROT_READ (1), PROT_WRITE (2), PROT_EXEC (4)

Errors: EINVAL (bad alignment/flags), ENOMEM (out of memory), EACCES (permission denied), EEXIST (region already mapped)

IPC : Ports

Errors: EBADF (invalid handle), ENOSPC (ring full), EAGAIN (non-blocking, nothing available), ETIMEDOUT (timeout exceeded)

IPC : Channels (typed MPMC)

Errors: EBADF (invalid handle), EPIPE (all endpoints disconnected), EAGAIN (try_recv on empty channel)

IPC : Semaphores

Errors: EBADF (invalid handle), EAGAIN (try_wait on zero semaphore)

PCI

Errors: EINVAL (invalid width/offset), EACCES (no PCI capability)

Async I/O

Process management

Errors: ECHILD (no child processes), EAGAIN (thread creation failed), ENOMEM (out of memory)

Futex

Errors: EAGAIN (value mismatch in WAIT), ETIMEDOUT (timeout expired), EFAULT (invalid address)

Signals

Process groups & sessions

User/group IDs

Misc process

File I/O

Open flags: O_RDONLY (0), O_WRONLY (1), O_RDWR (2), O_CREAT (0x40), O_TRUNC (0x200), O_APPEND (0x400), O_EXCL (0x800)

Errors: ENOENT (file not found), EACCES (permission denied), EBADF (bad fd), ENOTDIR (not a directory), EISDIR (is a directory), ENOSPC (disk full), EIO (I/O error)

File system operations

*at variants (relative to directory fd)

These syscalls resolve paths relative to a directory file descriptor instead of the process CWD. They are the POSIX-standard way to open, stat, and manipulate files safely in multi-threaded programs.

Special dirfd values

Syscall reference

Flags

Errors

EBADF (invalid dirfd), ENOENT (path not found), EACCES (permission denied), ENOTDIR (dirfd is not a directory), EEXIST (file exists for CREATE_EXCL), EINVAL (invalid flags)

Poll / I/O multiplexing

Network

Volume (block device)

Time

Clock IDs: CLOCK_REALTIME (0), CLOCK_MONOTONIC (1), CLOCK_PROCESS_CPUTIME_ID (2), CLOCK_THREAD_CPUTIME_ID (3)

Debug & miscellaneous

Module management

Silo management

ABI version

Common errno values

Syscall Layer

The userspace syscall crate is workspace/components/syscall (strat9-syscall).

Useful entry points:

• strat9_syscall::call for high-level wrappers
• strat9_syscall::number for syscall constants
• strat9_syscall::error for userspace error mapping
• strat9_syscall::data for shared data structs

API reference:

• strat9_syscall::call
• strat9_syscall::number
• strat9_syscall::error
• strat9_syscall::data

Changelog

Project stats

• Total commits: 554
• Latest tag: 0.1.0
• Repository: git.strat9-os.org

Recent commits (auto-generated)

• 2026-06-26 941a995 feat: update ABI changelog and documentation
• 2026-06-25 4fb871f Refactor error codes and syscall flags; implement getrandom syscall
• 2026-06-25 f0f891c docs: update published documentation
• 2026-06-25 9b31c08 docs: update published documentation
• 2026-06-25 a522fb8 Refactor NIC data plane and IPC transport statistics
• 2026-06-25 23cbead docs: update published documentation
• 2026-06-25 454a828 feat: add N2 data plane implementation with lock-free rings and enhance NIC interrupt handling
• 2026-06-25 1f1362b docs: update published documentation
• 2026-06-25 d1e838f feat: implement IPC transport layer with 3-level architecture
• 2026-06-25 411f5aa feat: add IPC transport layer support and enhance ICMP handling
• 2026-06-25 c034c91 docs: update published documentation
• 2026-06-25 bbad275 Implement IPC transport layer with lock-free ring and intrusive mailbox
• 2026-06-25 77b1a74 docs: add IPC architecture document (3 access levels)
• 2026-06-25 848baaf Merge branch 'feat/input-to-userspace' into 'main'
• 2026-06-25 5a3d69c feat: migrate input system to userspace
• 2026-06-24 1b98905 Merge branch 'test/smp-hardware-debug' into 'main'
• 2026-06-24 3fea3f3 SMP hardware debug, NVMe fixes, VGA refactor, telnetd hardening, docs
• 2026-06-17 f1bccb9 Merge branch 'fix/typed-irq-guard-allocator' into 'main'
• 2026-06-17 b1d7c35 buddy: use PreemptDisabled guardian on per-CPU frame caches (#37)
• 2026-06-17 1ca93d1 Merge branch 'fix/tech-debt-allocation-under-lock' into 'main'
• 2026-06-17 78e18ce Tech debt: allocation-under-lock and global-lock patterns (#50)
• 2026-06-16 6455a23 Merge branch 'fix/irq-token-encapsulation' into 'main'
• 2026-06-16 cb4ce4d Refactor: document IrqDisabledToken creation paths and encapsulation
• 2026-06-16 bdec79d Merge branch 'fix/arc-strong-count-wording' into 'main'
• 2026-06-16 c642da4 Fix: refine Arc::strong_count diagnostic wording to heuristic
• 2026-06-16 f85e757 Merge branch 'feat/spinlock-multi-watch-debug' into 'main'
• 2026-06-16 3fec849 Feat: replace single-lock trace with fixed-size multi-watch array
• 2026-06-16 84db9df Merge branch 'fix/slab-refill-irq-assert' into 'main'
• 2026-06-16 021fb49 Fix: add debug_assert IRQ-disabled invariant on slab refill
• 2026-06-16 8ebf658 Merge branch 'fix/heap-page-count-overflow' into 'main'
• 2026-06-16 d1f7eef Fix: use saturating arithmetic for vmalloc page count rounding
• 2026-06-16 99d4ede Merge branch 'fix/reparent-children-deterministic' into 'main'
• 2026-06-16 dcc239c Fix: make orphan reparenting deterministic by dropping links when PID 1 absent
• 2026-06-16 d2722ee Merge branch 'fix/legacy-pic-timer-parity' into 'main'
• 2026-06-16 e53a4b6 Fix: mirror LAPIC timer Ring-3 preemption policy in legacy PIC handler
• 2026-06-16 257b694 Merge branch 'fix/buddy-free-to-zone-logging' into 'main'
• 2026-06-16 18b1037 Fix: escalate free_to_zone protected-overlap to panic matching alloc side
• 2026-06-16 28bbc90 Merge branch 'fix/keyboard-lost-key-counter' into 'main'
• 2026-06-16 b19d6bf Fix keyboard driver: shared state, US extended keys, numpad, lost-key counter
• 2026-06-16 93302a5 docs: update published documentation
• 2026-06-16 b2edb49 Merge branch 'enhance-network-tools' into 'main'
• 2026-06-16 e4ab1a9 Enhance network stack, NIC drivers, USB/NVMe subsystems, and thermal management
• 2026-06-03 5ee7f8d Merge branch 'fix-some-mistake-in-network-stack' into 'main'
• 2026-06-03 0c40058 Refactor the network stack and add dual-stack userspace tooling
• 2026-05-24 aeade5e Code cleanup
• 2026-05-24 86c810e Raüs silo sshd
• 2026-05-24 40d4d46 Merge branch 'IPC-refactor' into 'main'
• 2026-05-24 b2bbcc0 Improve and fix IPC
• 2026-05-23 b7c3e27 Merge branch 'hunt-memory-corruption' into 'main'
• 2026-05-23 db23b53 Fix major memory leak and remove sshd silo

Publishing

One-command publication script

At repository root:

./publish-doc.sh

This script:

1. builds docs (cargo make docs-site)
2. regenerates ABI changelog auto section from git history
3. commits/pushes current branch changes
4. uploads built website to the remote vhost via SSH

The docs builder publishes:

1. mdBook pages under docs-site/
2. rustdoc for all workspace crates (cargo doc --workspace --no-deps)
3. a combined static site in build/docs-site