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 UEFI bootloader. 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[UEFI Bootloader]
    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

UEFI bootloader handoff

The kernel is loaded by the UEFI bootloader. The bootloader 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/boot.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-09-27 f64aff3c Implement console rendering and mouse input handling tasks
• 2026-09-13 3898c507 feat(bootloader, kernel, abi): homemade strat9 UEFI bootloader : rewrite with scheduler and memory hardening
• 2026-08-28 c03feb24 fix(abi): ENOTSUP 52→95, XFS EiB constant fix, decode_fixed roundtrip tests
• 2026-08-27 3ca6d7c6 feat: Add U-Boot setup script and boot protocol implementation
• 2026-08-25 88c52834 refactor(arch): unify x86_64 crate access via x86_crate_shim, complete riscv stubs
• 2026-08-25 c8ca94c4 refactor(arch): route shared code through arch::xshim, gate limine/x86 deps
• 2026-08-25 f3366e1d refactor(arch): migrate process/ and syscall/ call-sites to arch facade
• 2026-08-25 4399b5f5 test: pass 2 over full codebase — syscall, ABI data/handshake, NIC drivers, allocator
• 2026-08-25 88feb023 test(abi): exhaustive L0/L1 anti-regression suite
• 2026-08-27 09216d7c Merge branch 'fix/elf-loader-hardening' into 'main'
• 2026-08-27 2bad5b9b feat(elf): loader hardening (#62 #63 #64 #67 #68, groundwork #66)
• 2026-08-25 6ca7fef9 fix(ipc): security hardening, perf fixes and typed wire-format layer
• 2026-07-18 abb7dd7e feat(buddy): harden, optimize, and add kernel.toml configuration
• 2026-07-17 fe68f9aa fix(vfs,console,scheduler): VFS improvements, console perf, panic backtrace
• 2026-07-14 3a5eb69d feat(silo): replace Vec with heapless::Vec for bounded fields
• 2026-07-09 ab22b0d9 feat: 3-level IPC transport, N3 MMU thread migration, graphical silo, NIC/E1000 fixes
• 2026-06-25 5a3d69c4 feat: migrate input system to userspace
• 2026-06-24 3fea3f37 SMP hardware debug, NVMe fixes, VGA refactor, telnetd hardening, docs
• 2026-06-16 e4ab1a96 Enhance network stack, NIC drivers, USB/NVMe subsystems, and thermal management
• 2026-06-03 0c400585 Refactor the network stack and add dual-stack userspace tooling
• 2026-05-24 aeade5ef Code cleanup
• 2026-05-24 b2bbcc0b Improve and fix IPC
• 2026-05-23 db23b536 Fix major memory leak and remove sshd silo
• 2026-05-19 93c89275 async: implement and optimize async I/O completion handling
• 2026-05-18 7c5efb4d async: io_uring-like async I/O — ring, dispatch, AHCI bridge (Phases 1-4)
• 2026-05-14 cc4944a2 Refactor and clean up code in various modules
• 2026-05-14 ecc416df refactor: strate-init refactoring, ELF/VFS/signal hardening, TSC calibration fix
• 2026-05-08 f070d41c Add kernel entropy pool with interrupt-driven collection
• 2026-05-08 9dedb9f1 Implement robust list support (set_robust_list/get_robust_list)
• 2026-05-08 d2e90a2f Bridge clone() thread creation via SYS_THREAD_CREATE, add faccessat routing

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: 662
• Latest tag: 0.1.0
• Repository: git.strat9-os.org

Recent commits (auto-generated)

• 2026-09-27 f64aff3 Implement console rendering and mouse input handling tasks
• 2026-09-23 e53faf1 docs: update published documentation
• 2026-09-23 dec6766 Merge branch 'ELF-tuning-and-fix' into 'main'
• 2026-09-23 e724272 Fix : unify logging to log::*, reject null ET_EXEC entry, warn on zero-size COPY relocs
• 2026-09-14 4c008c5 docs: update published documentation
• 2026-09-13 981429b Merge branch 'fix/UEFI-bootloader' into 'main'
• 2026-09-13 3898c50 feat(bootloader, kernel, abi): homemade strat9 UEFI bootloader : rewrite with scheduler and memory hardening
• 2026-08-28 228eaa5 fix: regenerate corrupted Cargo.lock (stray merge conflict markers from rebase)
• 2026-08-28 93dd0e5 kernel: integrate cpuid.rs leaf1 detection diagnostics from ramfs-hardening WIP
• 2026-08-28 4eb5b3d Merge branch 'enhance-async-implementation' into 'main'
• 2026-08-28 00d83d7 feat(kernel): async I/O overhaul : userspace ring mapping, deferred completions, Scheme trait redesign
• 2026-08-28 6738421 Merge branch 'fix/errno-and-capabilities' into 'main'
• 2026-08-28 c03feb2 fix(abi): ENOTSUP 52→95, XFS EiB constant fix, decode_fixed roundtrip tests
• 2026-08-27 50a807d fix(framebuffer): update fill and blit operations to use dynamic detection
• 2026-08-27 7807362 Merge branch 'feat/graphics-performance' into 'main'
• 2026-08-27 7ed9263 style: apply rustfmt to paging.rs and framebuffer.rs
• 2026-08-24 aaf0fb6 fix(kernel): work around nightly LLVM ISel abort on pshufb/movntdq
• 2026-08-24 7087cff refactor(graphics): CanvasBuffer hygiene - S4/S5/S6 partial
• 2026-08-24 0e0d5fe perf(graphics): streaming stores for large fills/blits (S2)
• 2026-08-24 4aec188 perf(graphics): Write-Combining framebuffer via dedicated PAT entry; unified present throttling
• 2026-08-23 6b3cecc perf(graphics): batched blit API and lockless framebuffer info getters
• 2026-08-23 75af9ad perf(graphics): zero-copy VirtIO GPU presentation with coalesced damage
• 2026-08-23 706577f perf(graphics): SIMD pixel ingest + explicit-width wire protocol for /dev/display
• 2026-08-23 d4f597d perf(graphics): event-driven compositor with partial damage present
• 2026-08-27 067772e Merge branch 'feat/Replace-Limine-bootloader-with-U-Boot-for-multi-architecture-support' into 'main'
• 2026-08-27 3ca6d7c feat: Add U-Boot setup script and boot protocol implementation
• 2026-08-27 df64d6d Merge branch 'fixing-the-network-again' into 'main'
• 2026-08-27 eccb4d1 fix(net): ICMP reply handling + wasmi upgrade + clippy fixes
• 2026-08-27 25cc18b Merge branch 'feat/hal-arch-facade' into 'main'
• 2026-08-26 e725386 ok
• 2026-08-26 7262385 fix(arch,riscv64): dedupe duplicated stub modules in facade_riscv
• 2026-08-26 892cb03 fix(arch,riscv64): SegmentSelector newtype for gdt stub, safe unmap on stub mapper
• 2026-08-26 580b86f feat(ostd): Add/Sub operator impls for neutral PhysAddr/VirtAddr
• 2026-08-26 4260fbc fix(arch,riscv64): mapper::MapToError path fix inside OffsetPageTable impl
• 2026-08-26 60b50c6 feat(arch,riscv64): working Sv48 translate walker in stub mapper
• 2026-08-26 529715a feat(ipc,riscv64): Sv48 tagged-pointer layout for IntrusiveMailbox
• 2026-08-26 c086395 feat(arch,riscv64): PciDevice config-space accessors (stubbed, R5 wires ECAM)
• 2026-08-26 a790379 fix(arch,riscv64): MouseEvent struct + u8 KEY_* scancode parity with x86
• 2026-08-26 3e447a2 fix(arch,riscv64): restore unmap (tuple PhysFrame+MapperFlush) on stub mapper
• 2026-08-26 bf02f88 fix(arch,riscv64): unmap returns PhysFrame, Cr3::write/Cr3Flags::empty stubs
• 2026-08-26 dc404b5 fix(arch,riscv64): sealed PortValue trait for port stub (kills E0034)
• 2026-08-26 6d3f772 fix(arch,riscv64): port stub typed read/write impls, drop stale traits
• 2026-08-26 c9dbfb0 fix(arch): annotate ambiguous PhysFrame::containing_address call-sites
• 2026-08-26 8731a50 refactor(arch): Port trait-based reads, gate top TUI behind x86_64
• 2026-08-25 1da8196 fix(arch,riscv64): dedupe stubs, align keyboard read_char, FrameAllocator cfg
• 2026-08-25 daf86f5 fix(arch,riscv64): align stub signatures with x86 call-sites
• 2026-08-25 922d429 feat(arch,riscv64): full PciDevice struct + PCI surface stubs
• 2026-08-25 acba1cf feat(arch,riscv64): Mapper trait surface on Sv48 skeleton
• 2026-08-25 62d200e feat(arch,riscv64): real Sv48 scaffolding in x86_64-stub, ostd pointer helpers
• 2026-08-25 e96df8f refactor(arch): gate VGA-UI commands behind x86_64, complete riscv framebuffer_info stub

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

Architecture de tests Strat9-OS

Objectif : non-régression systématique pour chaque module du système — kernel, ABI, IPC, mémoire, VFS, drivers, composants userspace (Silos/Strates).

Statut initial constaté : ~66 #[test] dans tout le workspace, concentrés sur ipc/lockfree_ring, xfs-rs et fs-abstraction. Aucun stage de test en CI. cargo test --workspace échoue côté hôte (duplicate lang item panic_impl) car le kernel et les composants sont #![no_std] ciblant x86_64-unknown-none.

1. Les 5 couches de test (pyramide)

        ┌─────────────────────────────────────┐
   L4   │  Tests end-to-end QEMU (ISO boot)    │  lents, few, high value
        ├─────────────────────────────────────┤
   L3   │  Self-tests kernel in-QEMU           │  (feature `selftest`)
        ├─────────────────────────────────────┤
   L2   │  Unit tests no_std on host           │  pure logic, gated
        ├─────────────────────────────────────┤
   L1   │  Unit tests host (std)               │  ABI, parsers, codecs
        ├─────────────────────────────────────┤
   L0   │  Static ABI conformance assertions   │  compile-time
        └─────────────────────────────────────┘

L0 — Conformance ABI statique (compile-time)

• static_assertions::assert_eq_size! / assert_eq_align! / const_assert! sur toutes les structures #[repr(C)] traversant la frontière kernel ↔ userspace.
• Golden values des numéros de syscall : tout changement est une rupture d'ABI et doit être un commit explicite + bump de ABI_VERSION_MINOR.
• Fichier : workspace/abi/tests/abi_stability.rs.

L1 — Tests unitaires hôte (std)

Tout ce qui est logique pure sans dépendance matérielle :

• crate strat9-abi entière (errno, flags, parsing IP, codec IPC, payloads) ;
• math safe (safe_math), unicode, parseurs TOML de boot ;
• conversions POSIX ↔ Strat9 (musl-compat, relibc shims).
• Exécution : cargo test -p <crate> — doit rester vert en permanence.

L2 — Tests unitaires no_std sur hôte

Pour la logique kernel testable sans matériel (allocateurs, anneaux IPC, tables de capabilities, routage de schemes) :

• Pattern recommandé : extraire la logique pure dans des modules sans dépendance arch (mod pure), tester ces modules avec #[cfg(test)] compilés pour hôte ;
• Alternative : harness de test custom embarqué dans l'image (voir L3).

L2 — opérationnel : crate ombre workspace/kernel-l2-tests

Les modules purs du kernel sont compilés verbatim (#[path] includes) dans une crate hôte qui fournit des fakes fonctionnels : sync/irq (token factice), arch/x86_64/percpu (compteurs), silo, translation HHDM (offset réel vers une arena hôte → l'allocateur buddy travaille sur de la vraie mémoire). Les tests inline #[cfg(test)] du kernel s'exécutent enfin. Cible : cargo make test-kernel-l2. Modules couverts : sync/{fixed_queue,guardian,spinlock}, ipc/{message, lockfree_ring,mailbox}, memory/{boot_alloc,zone,frame,buddy}, namespace, boot/toml. Prochains candidats : ipc/channel, vfs (routeur de schemes), classes d'ordonnancement.

L3 — Self-tests kernel in-QEMU (feature selftest)

Le kernel dispose déjà de cargo make kernel-test + selftest.rs. Convention à généraliser :

• chaque sous-système déclare une fonction <module>_selftest() -> Result;
• l'orchestrateur affiche [selftest] PASS/FAIL <name> sur le port série ;
• sortie vérifiable mécaniquement : grep SELFTEST-FAIL sur la sortie série.

L4 — Tests d'intégration bout-en-bout QEMU

Silos utilisateurs dédiés (test_mem_region, test_exec, …) lancés depuis l'initfs ; le harnais QEMU vérifie la sortie série (TEST-PASS/TEST-FAIL) avec timeout. Cible cargo-make unique : cargo make ci-qemu-tests.

2. Matrice module → couches

* via extraction pure ou duplication contrôlée des constantes.

3. Conventions

1. Nommage : tests/<module>_*.rs (intégration), #[cfg(test)] mod tests (unitaires in-crate quand le crate compile en std pour les tests).
2. Un test = un comportement ; tables de cas (for case in CASES) privilégiées pour les parseurs/codecs.
3. Golden values pour toute constante cross-binaire (numéros syscall, layouts, opcodes IPC) : la régression est détectée même si aucun consumer n'est compilé.
4. Roundtrip systématique pour codecs : decode(encode(x)) == x + tests de corruption/troncature (bytes aléatoires déterministes, pas de RNG non seedé).
5. Chaque PR qui touche un module doit être accompagnée des tests de sa couche.

4. CI (roadmap)

Stage GitLab test entre build et release :

1. cargo test --workspace --exclude strat9-kernel ... (crates host-safe) ;
2. build kernel --features selftest (garde la compilation des selftests) ;
3. job optionnel QEMU : boot ISO + grep série (runner avec qemu-system-x86_64).

5. Questions ouvertes (à arbitrer)

1. Base de branche : branchée sur le HEAD de fix/ipc-scheme-security-review (5078255). Si vous préférez une base main, rebase trivial (fichiers nouveaux uniquement).
2. L2 kernel-hôte : préférer l'extraction de modules purs (refactor plus large, meilleure couverture) ou dupliquer les tests in-QEMU (zéro refactor, exécution plus lente) ? Recommandation : extraction progressive, en commençant par IPC.
3. QEMU en CI : un runner GitLab avec KVM/qemu est-il disponible ? Sinon TCG (lent mais suffisant pour L3/L4 courts).

Rapport de tests — findings

Issues découvertes par la suite anti-régression (test/anti-regression-suite). Chaque finding est référencé par un test qui le documente/pinne.

F1 — Build kernel cassé par le nightly non épinglé (bloquant) — ✅ RÉSOLU

Épinglé sur nightly-2026-08-20 (dernier bon vérifié : bisect 08-20 OK / 08-23 cassé, cause PR rust-lang/rust#160302 mergé le 23/08 à 21:33 UTC, commit fb6531d550e0). Le code exige en outre Step::forward/backward_overflowing (PR #155114, 09/07/2026) ⇒ fenêtre compatible [2026-07-10 .. 2026-08-22]. Correctif associé : [profile.dev] opt-level = 0 → 1 car O0 déclenche une ICE LLVM distincte (#158532) sur les intrinsèques AVX2. Builds debug, release, selftest et gate hôte tous vérifiés verts. framebuffer/x86/avx2.rs utilise #[target_feature(enable = "avx2")]. Sur rustc 1.100.0-nightly, activer sse/avx sur une cible soft-float (x86_64-unknown-none) est une erreur dure (lint x86_softfloat_sse). cargo make kernel échoue sur toutes les branches. Options :

1. (recommandé, immédiat) Épingler l'outilchain : channel = "nightly-2026-06-xx" dans rust-toolchain.toml — dernière version connue fonctionnelle ;
2. (long terme) Adapter avx2.rs : runtime detection + assembly inline ou wrapper compilé sans soft-float constraint.

F2 — VfsTimestamp::to_filetime déborde — ⏳ à faire

(secs + WINDOWS_EPOCH_OFFSET) as u64 * 10_000_000 sans arithmetic checkée : panic debug / wrap release au-delà de ~an 60000. Entrée contrôlée par le disque ou le réseau (chemins stat) ⇒ à traiter comme entrée hostile. Fix proposé : checked_mul → FsError::ArithmeticOverflow.

F3 — FsCapabilities::xfs()/btrfs() : valeurs PiB au lieu de EiB — ✅ RÉSOLU

XFS = 8 EiB réels ; btrfs clampé à u64::MAX (16 EiB = 2^64). Tests mis à jour. Commentaires « 8 EiB »/« 16 EiB », chaînes littérales à 5 facteurs 1024 ⇒ valeurs réelles 8 PiB / 16 PiB (16 EiB ne tient même pas dans u64). Décider : corriger les commentaires ou l'arithmétique.

F4 — parse_ipv6_literal sur-accepte le :: — ⏳ à durcir (RFC 4291)

RFC 4291 interdit :: quand 8 groupes explicites sont déjà présents ; le parseur accepte 1:2:3:4:5:6:7:8::. Sans danger immédiat (sortie bien formée) mais à durcir pour la conformité.

F5 — OpenReply n'implémente pas KnownLayout — ✅ RÉSOLU

KnownLayout dérivé via zerocopy (déjà dépendance) sur toute la surface de payloads repr(C) + InlineBlobHeader. Test de regression roundtrip decode_fixed ajouté pour chaque struct fixe.

F6 — ENOTSUP = 52 n'est pas la valeur Linux — ✅ RÉSOLU

Renommé 52 → 95 (= Linux x86_64) : constante ABI, selftest kernel, tests golden, entrée changelog ABI.

F7 — Test unitaire préexistant cassé depuis longtemps

strate-fs-abstraction/tests/unit_tests.rs importait fs_abstraction (ancien nom de crate) : aucun test de cette crate ne tournait depuis le renommage. Corrigé — preuve que l'absence de CI de test laisse pourrir la couverture silencieusement.

F8 — Constantes POSIX fausses dans strat9_syscall::flag — ✅ RÉSOLU

Trouvé lors de la passe 2 par la table dorée Linux :

• O_NOFOLLOW = 0o100000 → en réalité O_CLOEXEC sur Linux ; corrigé à 0o400000 ;
• O_NOCTTY = 0o400000 → en réalité O_NOFOLLOW sur Linux (!) ; corrigé à 0o000400, détecté par le test doré lui-même après le premier fix ;
• O_DSYNC = 0o02000000 → O_CLOEXEC aussi ; corrigé à 0o10000. La traduction posix_oflags_to_strat9 (crate abi) utilisait ses propres copies correctes — mais tout composant consommant ces constantes directement cassait. Leçon : les tables dorées attrapent ce que la relecture manuelle rate.

F9 — Test inline lockfree_ring::full_ring faux depuis sa création — ✅ CORRIGÉ

Découvert dès la première exécution réelle des tests inline du kernel (jamais possibles avant le harnais L2) : LockFreeRing::new(4, 64) crée 4 slots (next_power_of_two), donc 4 writes réussissent — le test attendait Full au 4ᵉ. Le test était off-by-one ; corrigé dans le bloc #[cfg(test)].

F10 — Port I/O out 0xe9 dans les primitives de sync — ✅ CONTOURNÉ

emit_trace_e9 (spinlock.rs) et d'autres traces diagnostiques émettent sur le port série E9 via asm!("out 0xe9") : instruction ring-0, SIGSEGV garanti en userspace. Compilé hors du binaire de test uniquement sous le cfg kernel_l2_host (posé par workspace/kernel-l2-tests/.cargo/config.toml) ; production inchangée.

F11 — La mailbox d'événements N1 est LIFO — ⚠️ épinglé, à arbitrer

notify_scheduler/poll_scheduler_events s'appuient sur IntrusiveMailbox (stack documentée « order is reversed on reception ») : les événements arrivent en ordre INVERSE d'émission. Sans gravité pour des événements indépendants, mais toute logique future dépendant de l'ordre causal (SchedTick avant Wakeup…) héritera de cette inversion. Épinglé AS IMPLEMENTED.

F12 — get_initfs_file_bytes ne retrouve pas les fichiers enregistrés avec préfixe — ⚠️ à vérifier au runtime

Le boot enregistre les modules Limine avec leur chemin complet (/initfs/fs-ext4, cf. log « Registered /initfs/fs-ext4 »), mais le lookup strip /initfs/ avant recherche : clé stockée /initfs/fs-ext4, clé cherchée fs-ext4 → raté. Conséquence possible : exec d'initfs via ce chemin cassé. Épinglé dans kernel_vfs_scheme.rs ; à confirmer sur le runtime QEMU.

F13 — Écrire dans un pipe à lecture fermée boucle à l'infini — ✅ CORRIGÉ

Trouvé par le harnais L2 (le test pendait indéfiniment) : Pipe::write évalue la condition « read end closed → EPIPE » via wait_until, mais le bras Err(_) => {} du match avalait l'erreur et relançait la boucle — spin 100% CPU infini au lieu de retourner EPIPE. Violation directe du contrat POSIX (SIGPIPE/EPIPE). Fix : propagation de l'erreur fatale (Err(e) => return Err(e)), seul Again reste transitoire. Impact production réel : tout processus écrivant dans un pipe dont le lecteur est mort (shell pipelines, IPC interne) se figeait.

F14 — Limine v8.7 panique sur les kernels fraîchement construits — 🔍 investigation ouverte

Constaté en tentant la validation L3/L4 : Limine PANIC: elf: No higher half PHDRs exist au chargement de boot():/boot/kernel.elf, sur NOTRE kernel selftest ET sur le kernel release reconstruit le 25/08 15:02. Pourtant readelf -l montre 4 PT_LOAD en higher-half (0xffffffff8000_0000+), entry point compris, ET_EXEC non-relocatable — le check elf64_get_ranges de Limine v8.7.0 (common/lib/elf.c:646) devrait compter 4 ranges. Éléments discriminants :

• les binaires Limine sont identiques (md5) dans les deux worktrees (clone v8.x-binary @ aad3edd, jan 2025) ;
• l'ISO construite ce matin depuis le VIEUX kernel (mai) bootait ;
• le kernel a donc changé, pas Limine → propriété ELF subtile en cause (memsz ~2 Go de .bss par segment ? ordre/alignement des PHDRs ?). ⚠️ CONTEXTE : le flux de boot est en migration (bootloader perso BIOS workspace/bootloader + create-image.sh, commits UEFI sur d'autres branches). À arbitrer : réparer la chaîne Limine (utile pour les selftests L3/L4 automatisés) ou basculer le harnais QEMU sur le bootloader perso. En attendant, la porte CI L0/L1/L2 (364 tests) ne dépend pas du boot QEMU.

Couverture ajoutée (L2 — code kernel réel sur hôte)

| kernel-l2-tests/tests/kernel_vfs_scheme.rs | 7 | finalize_pseudo_stat, registre KernelScheme (/initfs), routeur global de schemes, F12 |

| kernel-l2-tests/tests/kernel_vfs_fd.rs | 13 | OpenFile (offset partagé POSIX, permissions, EOF), FileDescriptorTable (réuse plus bas fd, dup F_DUPFD, cloexec), Nice saturé + AtomicNice |

| kernel-l2-tests/tests/kernel_pipes.rs | 9 | pipes kernel: FIFO, wraparound 4096, EOF/EPIPE lifecycle (F13), registre PipeScheme |

Total porte CI : 364 tests verts.

Reste candidat L2 : classes d'ordonnancement complètes (nécessitent une fake AddressSpace), fake userslice pour handlers read/write d'IpcScheme.

Total porte CI : 327 tests verts.

Reste candidat L2 (documenté) : vfs/scheme.rs + routeur — bloqué par memory/userslice.rs qui valide les pointeurs userspace contre les tables de pages x86 réelles ; nécessitera une fake de validation de région.

* comptage approximatif des modules inclus. Harnais : crate ombre workspace/kernel-l2-tests — modules kernel inclus verbatim via #[path], fakes fonctionnels pour IRQ/percpu/silo/HHDM.

Porte CI : cargo make ci-tests — 162+ tests hôte verts (stage GitLab test).

Porte CI : cargo make ci-tests (stage GitLab test, job test-host).

Prochaines étapes proposées (L2/L3/L4)

1. L2 kernel-hôte : extraire la logique pure IPC/mémoire en modules testables hôte.
2. L3 : généraliser le pattern selftest (PASS/FAIL série grep-able) à tous les sous-systèmes kernel.
3. L4 : harnais QEMU automatisé (boot ISO + grep série + timeout) en job GitLab.