Project Status

ostoo is a hobby x86-64 kernel written in Rust, following the Writing an OS in Rust blog series by Philipp Oppermann. All twelve tutorial chapters have been completed and the project has gone significantly beyond the tutorial.

Workspace Layout

Target triple: x86_64-os (custom JSON target, bare-metal, no std). Build tooling: cargo-xbuild + bootimage (BIOS bootloader). Toolchain: current nightly (floating, rust-toolchain.toml).

Completed Tutorial Chapters

1–2. Freestanding Binary / Minimal Kernel

• #![no_std], #![no_main], custom panic handler.
• bootloader crate provides the BIOS boot stage and passes a BootInfo struct.
• Entry point via entry_point! macro (libkernel_main in kernel/src/main.rs).

3. VGA Text Mode

• libkernel/src/vga_buffer/mod.rs — a Writer behind an IrqMutex.
• print! / println! macros available globally.
• Volatile writes to avoid compiler optimisation of MMIO.
• Hardware cursor (CRTC registers 0x3D4/0x3D5) kept in sync on every write.
• redraw_line(start_col, buf, len, cursor) for in-place line editing.
• Fixed status bar at row 0 (status_bar! macro, white-on-blue); updated by status_task every 250 ms with thread index, context-switch count, task queue depths, and uptime.
• Timeline strip at row 1: scrolling coloured blocks, one per context switch, colour-coded by thread index.

4. Testing

• Custom test framework (custom_test_frameworks feature).
• Integration tests in kernel/tests/: basic_boot, heap_allocation, should_panic, stack_overflow.
• QEMU isa-debug-exit device used to signal pass/fail to the host.
• Serial port (libkernel/src/serial.rs) used for test output.

5–6. CPU Exceptions / Double Faults

• IDT set up in libkernel/src/interrupts.rs via lazy_static.
• Handlers: breakpoint, page fault (panics), double fault (panics).
• Double fault uses a dedicated IST stack (GDT TSS entry).
• GDT + TSS initialised in libkernel/src/gdt.rs.

7. Hardware Interrupts

• 8259 PIC (chained) initialised via pic8259; remapped to IRQ vectors 32–47.
• PIC is later disabled once the APIC is configured.
• Timer interrupt handler (IRQ 0): increments tick counter, wakes timer futures.
• Keyboard interrupt handler (IRQ 1): reads scancode from port 0x60, pushes it into the async scancode queue.

8–9. Paging / Paging Implementation

• libkernel/src/memory/mod.rs — RecursivePageTable (PML4 slot 511 self-referential); MMIO bump allocator at 0xFFFF_8002_0000_0000 with BTreeMap cache for idempotency; physical memory identity map kept for DMA address translation only (phys_mem_offset from bootloader).
• libkernel/src/memory/frame_allocator.rs — BootInfoFrameAllocator walks the bootloader memory map to hand out usable physical frames.
• libkernel/src/memory/vmem_allocator.rs — DumbVmemAllocator hands out a sequential range of virtual addresses (no reclamation); currently unused in production — the MMIO bump allocator in MemoryServices handles all virtual address allocation at runtime.

10. Heap Allocation

• Kernel heap mapped at 0xFFFF_8000_0000_0000, size 512 KiB (libkernel/src/allocator/mod.rs).
• Global allocator: linked_list_allocator::LockedHeap.
• extern crate alloc available; Box, Vec, Rc, BTreeMap, etc. all work.

11. Allocator Designs

• Bump allocator implemented in libkernel/src/allocator/bump.rs (O(1) alloc, no free).
• linked_list_allocator is the active global allocator (can be swapped by changing the static ALLOCATOR line in libkernel/src/lib.rs).

12. Async/Await

• Task abstraction in libkernel/src/task/mod.rs — pinned boxed futures with atomic TaskId.
• Simple round-robin executor in task/simple_executor.rs.
• Full waker-based executor in task/executor.rs:
  • Ready tasks in a VecDeque, waiting tasks in a BTreeMap.
  • Wake queue (crossbeam_queue::ArrayQueue) for interrupt-safe wakeups.
  • sleep_if_idle uses sti; hlt to avoid busy-waiting.

Beyond the Tutorial

Timer

• libkernel/src/task/timer.rs — LAPIC tick counter; TICKS_PER_SECOND = 1000.
• Delay future: resolves after a given number of ticks.
• Mailbox::recv_timeout(ticks) races inbox against a Delay.

Preemptive Multi-threaded Scheduler

• libkernel/src/task/scheduler.rs — round-robin preemptive scheduler driven by the LAPIC timer at 1000 Hz; 10 ms quantum (QUANTUM_TICKS = 10).
• Assembly stub lapic_timer_stub saves all 15 GPRs + iret frame on the current stack, then calls preempt_tick(current_rsp) -> new_rsp in Rust.
• preempt_tick advances the tick counter, acknowledges the LAPIC interrupt, decrements the quantum, and when it expires saves the old RSP, selects the next ready thread, and returns its saved_rsp.
• scheduler::migrate_to_heap_stack(run_kernel) allocates a 64 KiB heap stack and switches thread 0 off the bootloader’s lower-half stack onto PML4 entry 256 (high canonical half), so it survives CR3 switches into user page tables.
• scheduler::init() registers the boot context as thread 0.
• scheduler::spawn_thread(entry) allocates a 64 KiB stack, synthesises an iret frame, and enqueues the new thread.
• The kernel boots two executor threads (threads 0 and 1) that share the same async task queue; tasks are transparently dispatched across both.
• Shell command threads shows the current thread index and total context switches since boot.

Actor System (devices/, devices-macros/)

• DriverTask trait: name(), run(inbox, handle).
• Mailbox<M> / Inbox<M> MPSC queue; ActorMsg<M,I> envelope wraps inner messages, info queries, and erased-type info queries.
• Process registry (libkernel/src/task/registry.rs): actors register by name; registry::get::<M,I>(name) returns a typed sender handle.
• ErasedInfo registry: actors register a Box<dyn Fn() -> ...> so the shell can query any actor’s info without knowing its concrete type.

Proc-macro attributes (used inside #[actor] blocks)

The macro generates a unified poll_fn loop when #[on_tick] or #[on_stream] are present, racing all event sources in a single future.

User Space and Process Isolation

• Full ring-3 process support with per-process page tables, SYSCALL/SYSRET, and preemptive scheduling. Process exit and execve properly free user-half page tables and data frames (with refcount-aware shared frame handling).
• 35+ Linux-compatible syscalls in osl/src/syscalls/.
• Per-process FD table, CWD tracking, parent/child relationships, zombie lifecycle with wait4/reap.
• ELF loader for static x86-64 binaries; initial stack with argc/argv/auxv.
• IPC channels with fd-passing (capability transfer) — syscalls 505–507. See docs/ipc-channels.md.
• Shared memory via shmem_create (syscall 508) + mmap(MAP_SHARED) — anonymous shared memory backed by reference-counted physical frames. See docs/mmap-design.md Phase 5b.
• Notification fds via notify_create (509) + notify (510) — general- purpose inter-process signaling through completion ports (OP_RING_WAIT). See docs/completion-port-design.md Phase 4.
• Console input buffer with foreground PID routing and blocking read(0).
• Async-to-sync bridge (osl/src/blocking.rs) for VFS calls from syscall context.
• See docs/userspace-plan.md for the full roadmap (Phases 0–6 complete; Phase 7 signals not yet started).

Userspace Libraries (user/include/ostoo.h, user-rs/rt/)

• C library (libostoo.a): shared header user/include/ostoo.h with struct definitions, syscall numbers, opcodes, and flags. Static library user/lib/libostoo.a provides typed syscall wrappers for all 12 custom syscalls (501–512), output helpers (puts_stdout, put_num, put_hex), conversion helpers (itoa_buf, simple_atoi), and ring buffer access helpers (sq_entry, cq_entry). All 21 demo programs have been migrated to use the shared library, eliminating per-file boilerplate.
• Rust library (ostoo-rt crate): two modules added to the existing user-rs/rt/ runtime crate. sys module provides raw syscall wrappers and repr(C) struct definitions matching the kernel ABI. ostoo module provides safe RAII types (CompletionPort, IpcSend/IpcRecv, SharedMem, NotifyFd, IrqFd, IoRing) with automatic fd cleanup on drop, plus builder methods on IoSubmission for each opcode.

Userspace Shell (user/src/shell.c)

• Primary user interface: musl-linked C binary, auto-launched on boot from /bin/shell via kernel/src/main.rs.
• Line editing: read char-by-char, echo, backspace, Ctrl+C (cancel), Ctrl+D (exit on empty line).
• Built-in commands: echo, pwd, cd, ls, cat, pid, export, env, unset, exit, help.
• Environment variables: shell maintains an env table, passes it to children. Kernel provides defaults: PATH=/host/bin, HOME=/, TERM=dumb, SHELL=/bin/shell.
• External programs: posix_spawn(path) + waitpid.
• Built with Docker-based musl cross-compiler (scripts/user-build.sh).
• Sources in user/src/, binaries output to user/bin/.
• See docs/userspace-shell.md for full design.

Kernel Shell (kernel/src/shell.rs) — fallback

• #[actor]-based shell actor, active when no userspace shell is running.
• Prompt includes CWD: ostoo:/path> .
• Commands: help, echo, driver <start|stop|info>, blk <info|read|ls|cat>, ls, cat, pwd, cd, mount, exec, test.
• Info commands (cpuinfo, meminfo, etc.) migrated to /proc; accessible via cat /proc/<file>.

Keyboard Actor (kernel/src/keyboard_actor.rs)

• #[actor] + #[on_stream(key_stream)]; registered as "keyboard".
• Foreground routing: when a user process is foreground, raw keypresses are delivered to console::push_input() for userspace read(0).
• When kernel is foreground: full readline-style line editing:
  • Cursor movement: ← → / Ctrl+B/F, Home/End / Ctrl+A/E
  • Editing: Backspace, Delete, Ctrl+K (kill to end), Ctrl+U (kill to start), Ctrl+W (delete word)
  • History: ↑↓ / Ctrl+P/N, 50-entry VecDeque, live-buffer save/restore
  • Ctrl+C clears the line; Ctrl+L clears the screen
• Dispatches complete lines to the kernel shell via ShellMsg::KeyLine.

virtio-blk Block Device (devices/src/virtio/)

• virtio-drivers 0.13 crate provides the virtio protocol; the kernel supplies KernelHal implementing Hal for DMA allocation, MMIO mapping, and virtual→physical address translation.
• QEMU Q35 machine; PCIe ECAM at physical 0xB000_0000 mapped at boot via MemoryServices::map_mmio_region. PciRoot is generic over MmioCam<'static>.
• VirtioBlkActor actor: handles Read and Write messages using the non-blocking virtio-drivers API (read_blocks_nb / complete_read_blocks) with a busy-poll CompletionFuture for MVP.
• KernelHal::share performs a full page-table walk (translate_virt) so that heap-allocated BlkReq/BlkResp/data buffers produce correct physical addresses for the device.
• Shell commands: blk info, blk read <sector>.
• See docs/virtio-blk.md for full details.

VirtIO 9P Host Directory Sharing (devices/src/virtio/p9*.rs)

• VirtIO 9P (9P2000.L) driver for sharing a host directory into the guest, providing a Docker-volume-like workflow: edit files on the host, they appear instantly in the guest.
• p9_proto.rs — minimal 9P2000.L wire protocol: 8 message pairs (version, attach, walk, lopen, read, readdir, getattr, clunk).
• p9.rs — P9Client high-level client wrapping VirtIO9p<KernelHal, PciTransport>. Synchronous API behind SpinMutex; performs version handshake + attach on construction. Public methods: list_dir, read_file, stat.
• QEMU shares ./user directory via -fsdev local,...,security_model=none
  • -device virtio-9p-pci,...,mount_tag=hostfs.
• Mounted at /host (always) and at / as fallback when no virtio-blk disk is present, so /bin/shell auto-launch works without a disk image.
• PCI device IDs: 0x1AF4:0x1049 (modern), 0x1AF4:0x1009 (legacy).
• Read-only for MVP; no write/create/delete support.
• See docs/virtio-9p.md for full details.

exFAT Filesystem (devices/src/virtio/exfat.rs)

• Read-only exFAT driver with no external dependencies.
• Auto-detects bare exFAT, MBR-partitioned, and GPT-partitioned disk images.
• Implements: boot sector parsing, FAT chain traversal, directory entry set parsing (File / Stream Extension / File Name entries), and recursive path walking with case-insensitive ASCII matching.
• File reads capped at 16 KiB; peak heap usage during ls ≈ 5 KiB.
• See docs/exfat.md for full details.

VFS Layer (devices/src/vfs/)

• Uniform path namespace over multiple filesystems; shell no longer calls filesystem drivers directly.
• Enum dispatch (AnyVfs) avoids Pin<Box<dyn Future>> trait objects.
• Mount table (MOUNTS: SpinMutex<Vec<(String, Arc<AnyVfs>)>>) sorted longest-mountpoint-first; the Arc is cloned out before any .await so the lock is never held across a suspension point.
• ExfatVfs — wraps a BlkInbox and delegates to the exFAT driver.
• Plan9Vfs — wraps an Arc<P9Client> and delegates to the 9P client. Maps P9Error to VfsError (ENOENT→NotFound, ENOTDIR→NotADirectory, etc.).
• ProcVfs — synthetic filesystem; no block I/O. All system info commands have been migrated from the shell to /proc virtual files:
  • /proc/tasks — ready / waiting task counts from the executor.
  • /proc/uptime — seconds since boot from the LAPIC tick counter.
  • /proc/drivers — name and state of every registered driver.
  • /proc/threads — current thread index and context-switch count.
  • /proc/meminfo — heap usage, frame allocator stats, known virtual regions.
  • /proc/memmap — physical memory regions from the bootloader memory map.
  • /proc/cpuinfo — CPU vendor, family/model/stepping, CR0/CR4/EFER/RFLAGS.
  • /proc/pmap — page table walk with coalesced contiguous regions.
  • /proc/idt — IDT vector assignments (exceptions, PIC, LAPIC, dynamic).
  • /proc/pci — enumerated PCI devices.
  • /proc/lapic — Local APIC state and timer configuration.
  • /proc/ioapic — I/O APIC redirection table entries.
  • /proc/irq_stats — per-slot IRQ counters (total, delivered, buffered, spurious).
• Shell commands: ls, cat, cd use the VFS API; mount manages the mount table at runtime (mount, mount proc <mp>, mount blk <mp>).
• /proc is always mounted at boot; exFAT / is mounted if virtio-blk is present; 9p /host is mounted if virtio-9p is present (and 9p falls back to / when no disk image exists).
• See docs/vfs.md for full design notes.

Completion Port Async I/O (osl/src/io_port.rs)

• io_uring-style completion-based async I/O subsystem.
• Kernel object: CompletionPort (libkernel/src/completion_port.rs) — bounded queue of completions with single-waiter blocking semantics.
• FdObject enum in libkernel/src/file.rs provides type-safe polymorphism for the fd table (File | Port), replacing the previous trait-object downcast approach.
• IrqMutex protects the CompletionPort for ISR-safe post() from interrupt context.
• Syscalls: io_create (501), io_submit (502), io_wait (503), io_setup_rings (511), io_ring_enter (512).
• Supported operations: OP_NOP (immediate), OP_TIMEOUT (async timer via executor), OP_READ / OP_WRITE (async — user buffers are copied to/from kernel memory during io_submit/io_wait; the actual I/O runs on executor tasks so io_submit returns immediately), OP_IRQ_WAIT (hardware interrupt delivery — ISR masks GSI and posts completion; rearm via another submit unmasks).
• Shared-memory SQ/CQ rings (Phase 5): io_setup_rings allocates ring pages as shmem fds; userspace writes SQEs to the SQ ring and reads CQEs from the CQ ring. io_ring_enter kicks the kernel and/or blocks for completions.
• FileHandle trait has poll_read / poll_write methods (default impls delegate to sync read/write). PipeReader and ConsoleHandle override poll_read with waker-based async semantics so completion port reads never block executor threads.
• Userspace demo programs: io_demo.c (smoke test), io_pingpong.c / io_pong.c (parent-child IPC via completion port).
• See docs/completion-port-design.md for the full phased roadmap (all phases complete).

IRQ File Descriptors (libkernel/src/irq_handle.rs, osl/src/irq.rs)

• Userspace interrupt delivery via irq_create(gsi) syscall (504).
• IrqInner tracks GSI, vector, slot, and saved IO APIC redirection entry.
• ISR handler (irq_fd_dispatch) masks the GSI via libkernel::apic::mask_gsi and posts a completion to the associated CompletionPort. For keyboard (GSI 1) and mouse (GSI 12), the ISR reads port 0x60 and drains all available bytes per interrupt (up to 16 per ISR invocation).
• 64-entry scancode ring buffer per slot prevents lost scancodes between rearms. arm_irq bulk-drains the entire buffer into completions.
• Per-slot atomic IRQ counters (total, delivered, buffered, spurious, wrong_source) visible via /proc/irq_stats.
• On close, the original IO APIC entry is restored.
• Demo: user/irq_demo.c — keyboard scancode display via OP_IRQ_WAIT.

IPC Channels (libkernel/src/channel.rs, osl/src/ipc.rs)

• Capability-based IPC channels for structured message passing between processes.
• Unidirectional with configurable buffer capacity: capacity=0 for synchronous rendezvous (seL4-style), capacity>0 for async buffered.
• Fixed 48-byte messages: tag (u64) + data[3] (u64) + fds[4] (i32).
• fd-passing (capability transfer): sender’s fds are extracted at send time, kernel objects are stored in the channel, and new fds are allocated in the receiver’s fd table at recv time. Cleanup on drop for undelivered messages.
• Completion port integration: OP_IPC_SEND (5) and OP_IPC_RECV (6) for multiplexing IPC with timers, IRQs, and file I/O.
• Syscalls: ipc_create (505), ipc_send (506), ipc_recv (507).
• Demos: ipc_sync.c, ipc_async.c, ipc_port.c, ipc_fdpass.c.
• See docs/ipc-channels.md for full design.

Deadlock Detection (libkernel/src/spin_mutex.rs)

• All spin::Mutex locks replaced with SpinMutex — a drop-in wrapper that counts spin iterations and panics after a threshold, turning silent hangs into actionable diagnostics with serial output.
• SpinMutex: 100M iteration limit (~100 ms) — allows for legitimate preemption contention on a single-core scheduler.
• IrqMutex: 10M iteration limit (~10 ms) — interrupts disabled means no preemption, so any contention indicates a true deadlock.
• deadlock_panic() writes directly to COM1 (0x3F8) bypassing SERIAL1’s lock, then panics.

POSIX Signals (libkernel/src/signal.rs, osl/src/signal.rs)

• Phases 1–2: signal infrastructure, delivery on SYSCALL return, Ctrl+C/SIGINT, signal-interrupted syscalls (EINTR).
• rt_sigaction (13): install/query signal handlers (SA_SIGINFO, SA_RESTORER).
• rt_sigprocmask (14): SIG_BLOCK/UNBLOCK/SETMASK for the signal mask.
• kill (62): send a signal to a specific pid; wakes interruptible blocks.
• rt_sigreturn (15): restore context from rt_sigframe after handler returns.
• Signal delivery via check_pending_signals in the SYSCALL return path: constructs a Linux-ABI-compatible rt_sigframe on the user stack, rewrites the saved register frame so sysretq “returns” into the handler.
• Ctrl+C: keyboard actor queues SIGINT on foreground_pid(), wakes blocked console reader.
• EINTR: blocking syscalls (sys_wait4, PipeReader::read) set a per-process signal_thread field; sys_kill unblocks it so the syscall returns EINTR. The shell forwards SIGINT to child processes on EINTR from waitpid.
• Default actions: SIG_DFL terminate (SIGKILL, SIGTERM, etc.) or ignore (SIGCHLD).
• Demos: user/sig_demo.c (SIGUSR1 self-signal), user/sig_int.c (Ctrl+C interrupt test), userspace shell handles SIGINT via sigaction.
• See docs/signals.md for full design.

Dummy Driver (devices/src/dummy.rs)

• Example actor with #[on_tick] heartbeat, #[on_message(SetInterval)], and #[on_info].
• Demonstrates the full actor feature set.

ACPI Parsing

• kernel/src/kernel_acpi.rs implements an AcpiHandler that accesses physical ACPI regions via the bootloader’s identity map (phys + physical_memory_offset); no dynamic page mapping is required since all ACPI tables live in physical RAM.
• Calls acpi::search_for_rsdp_bios to locate and parse ACPI tables.
• On boot the interrupt model is printed; APIC vs legacy PIC is detected.

APIC Module (libkernel/src/apic/)

• APIC code lives in libkernel::apic, mapped at 0xFFFF_8001_0000_0000.
• libkernel/src/apic/local_apic/ — Local APIC register access via MMIO and MSR.
• libkernel/src/apic/io_apic/ — I/O APIC register access via MMIO.
• libkernel::apic::init() maps the Local APIC and all I/O APICs from the ACPI table, routes ISA IRQs 0 (timer) and 1 (keyboard) through the I/O APIC to IDT vectors 0x20 and 0x21, then disables the 8259 PIC.
• libkernel::apic::calibrate_and_start_lapic_timer() uses the PIT as a reference to measure the LAPIC bus frequency, starts the LAPIC timer in periodic mode at 1000 Hz, then masks the PIT’s I/O APIC entry so it no longer fires.

Logging

• libkernel/src/logger.rs wraps the VGA println! macro as a log::Log implementation.
• log::{debug, info, warn, error} macros usable throughout the kernel.
• Initialised early in libkernel_main.

CPUID

• libkernel/src/cpuid.rs — thin wrapper around raw-cpuid; init() called during kernel init.

Known Issues / Technical Debt

Heap Size

The heap is a fixed 1 MiB at 0xFFFF_8000_0000_0000. Kernel thread stacks are allocated from a separate stack arena (libkernel/src/stack_arena.rs) at 0xFFFF_8000_0010_0000 (16 × 64 KiB = 1 MiB), keeping large stack allocations off the general-purpose heap and eliminating fragmentation. The arena uses a bitmap for O(1) alloc/free with RAII slot handles. The heap is now used only for small driver/task allocations. The DumbVmemAllocator has no reclamation path, so virtual address space for MMIO/ACPI mappings is consumed monotonically.

virtio-blk Single-sector I/O

Block I/O uses IRQ-driven completion via AtomicWaker, but is still limited to one 512-byte sector per request.

exFAT Write Support

The exFAT driver is read-only. All filesystem state changes (create, write, delete) are unsupported.

ProcVfs File Sizes Reported as Zero

VfsDirEntry::size is 0 for all /proc entries because the content length is not known until the data is serialised. This is cosmetically wrong in ls output but functionally harmless.

Possible Next Steps

Completion Port — All Phases Complete

• Phases 1–4 (core, read/write, OP_IRQ_WAIT, OP_RING_WAIT) — see sections above.
• Phase 5: Shared-memory SQ/CQ rings — implemented. io_setup_rings (511) allocates shared SQ/CQ ring pages exposed as shmem fds. io_ring_enter (512) processes SQ entries and waits for CQ completions. Dual-mode post() writes simple CQEs directly to the shared CQ ring; deferred completions (OP_READ, OP_IPC_RECV) are flushed in syscall context. Test: ring_sq_test.

Memory Management

1. Larger / growable heap — demand-paged heap that grows on fault, or a larger static allocation. 1 MiB is tight with concurrent processes.

2. Reclaiming virtual address space — replace DumbVmemAllocator with a proper free-list allocator so MMIO mappings can be released.

3. File-backed MAP_SHARED — anonymous shared memory (via shmem_create) is complete; file-backed MAP_SHARED with inode page cache remains future work. See docs/mmap-design.md Phase 5c.

Process Model

4. Signals Phase 3+ — Phases 1–2 (basic signal delivery + Ctrl+C/SIGINT + EINTR) are complete: rt_sigaction, rt_sigprocmask, kill, signal delivery on SYSCALL return, rt_sigreturn, Ctrl+C → SIGINT to foreground process, signal-interrupted blocking syscalls (EINTR). Remaining: exception-generated signals (SIGSEGV, SIGILL), SIGCHLD on child exit. See docs/signals.md.

5. fork + CoW page faults — standard POSIX fork. clone(CLONE_VM|CLONE_VFORK) and execve are now implemented, enabling unpatched musl posix_spawn and Rust std::process::Command. Full fork with CoW still requires a page fault handler and frame reference counting.

Drivers & I/O

6. Multi-sector DMA — batch multiple sectors per virtio request to reduce queue round-trips for directory scans and file reads.

7. exFAT write support — directory entry creation, FAT chain allocation, and sector writes to enable touch, mkdir, cp, rm.

Compositor & Window Management

The userspace compositor (/bin/compositor) is a Wayland-style display server with full input routing and window management.

• Display: Takes exclusive ownership of the BGA framebuffer via framebuffer_open (515). Double-buffered compositing with painter’s algorithm. Cursor-only rendering optimization patches small rectangles for mouse movement instead of full recomposite.
• Input: Connects to /bin/kbd (keyboard) service via the service registry. Mouse input is integrated directly — the compositor claims IRQ 12 and decodes PS/2 packets inline (no separate mouse driver process). Key events forwarded to focused window. Mouse events drive cursor, focus, drag, and resize.
• CDE-style decorations: Server-side window decorations inspired by CDE/Motif — 3D beveled borders (BORDER_W=4, BEVEL=2), 24px title bar with centered title, CDE-style close button, sunken inner bevel around client area. Blue-grey color palette.
• Window management: Click-to-focus with Z-order raise. Title bar drag to move. Edge/corner drag to resize with context-sensitive cursor icons (diagonal, horizontal, vertical double-arrows). Close button removes window.
• Resize protocol: On resize completion, compositor allocates a new shared buffer and sends MSG_WINDOW_RESIZED (tag 7) with the new buffer fd. Terminal emulator remaps buffer, recalculates dimensions, and redraws.
• Terminal emulator (/bin/term): Compositor client that spawns /bin/shell with pipe-connected stdin/stdout. VT100 parser with color support. Character-level screen buffer (Cell array + per-row wrapped flags) enables text reflow on resize: logical lines are extracted, re-wrapped to the new width, and pixels regenerated from the cell buffer. Cursor position is preserved across resize.
• See docs/compositor-design.md and docs/display-input-ownership.md.

Microkernel Path

8. Microkernel Phase B — kernel primitives for userspace drivers: device MMIO mapping, DMA syscalls. IRQ fd (syscall 504 + OP_IRQ_WAIT) and MAP_SHARED (via shmem_create 508) are complete. Remaining items unblock userspace NIC driver. See docs/microkernel-design.md.

9. Networking — virtio-net driver + smoltcp TCP/IP stack. The completion port is ready to back it once the NIC driver lands. See docs/networking-design.md.

Preemptive Scheduler & Multi-threaded Async Executor

Overview

The kernel uses a round-robin preemptive scheduler built on top of the LAPIC timer (1000 Hz). Every 10 ms (configurable via QUANTUM_TICKS) the timer ISR saves the current CPU state and switches to the next ready thread, regardless of what that thread was doing. This prevents any single async task — even one that busy-loops — from starving all others.

The async executor’s state lives in global statics, so multiple kernel threads can pull and poll tasks from the same shared queue concurrently.

Thread Lifecycle

        spawn_thread()
             │
             ▼
          [ Ready ] ◄──────────────────────────────┐
             │  (selected by scheduler)             │
             ▼                                      │
         [ Running ]  ──── quantum expired ─────────┘

Threads cycle between Ready and Running in strict round-robin order. There is no blocked/sleeping state for threads — a thread that has nothing to do (idle executor loop) calls HLT until an interrupt wakes it.

Thread 0 is the initial kernel thread. Early in boot, libkernel_main calls scheduler::migrate_to_heap_stack(run_kernel) which allocates a 64 KiB heap stack and switches RSP to it before continuing. This moves thread 0 off the bootloader’s lower-half stack onto PML4 entry 256 (high canonical half), so its stack survives CR3 switches into user page tables.

Additional threads are created with scheduler::spawn_thread(entry: fn() -> !). The entry function must never return; in practice it calls executor::run_worker().

Context Switch Mechanism

LAPIC timer IDT entry

The IDT entry for LAPIC_TIMER_VECTOR (0x30) is set with set_handler_addr pointing directly at lapic_timer_stub. This bypasses the extern "x86-interrupt" wrapper so the stub can manipulate RSP freely.

Assembly stub (lapic_timer_stub)

lapic_timer_stub:
    push rax; push rbx; push rcx; push rdx
    push rsi; push rdi; push rbp
    push r8;  push r9;  push r10; push r11
    push r12; push r13; push r14; push r15
    sub  rsp, 512           // allocate FXSAVE area
    fxsave [rsp]            // save x87/MMX/SSE state
    mov  rdi, rsp           // current_rsp → first argument
    call preempt_tick       // returns new rsp in rax
    mov  rsp, rax           // switch to (possibly new) thread's stack
    fxrstor [rsp]           // restore x87/MMX/SSE state
    add  rsp, 512           // deallocate FXSAVE area
    pop r15; pop r14; pop r13; pop r12
    pop r11; pop r10; pop r9;  pop r8
    pop rbp; pop rdi; pop rsi
    pop rdx; pop rcx; pop rbx; pop rax
    iretq

The CPU pushes an interrupt frame (SS/RSP/RFLAGS/CS/RIP, 40 bytes) before the stub runs. The stub pushes 15 GPRs (120 bytes) and then allocates a 512-byte FXSAVE area for x87/MMX/SSE register state. Together that is 672 bytes = 42 × 16, so RSP is 16-byte aligned for both fxsave [rsp] (requires 16-byte alignment) and the call instruction (SysV ABI: RSP + 8 aligned at function entry).

preempt_tick(current_rsp: u64) -> u64

Runs entirely on the current thread’s stack (inside the call/ret pair), then returns the next thread’s saved_rsp in RAX.

1. Increments the global tick counter and wakes sleeping async tasks.
2. Sends LAPIC EOI.
3. Locks SCHEDULER (interrupts already off — no deadlock risk).
4. If not yet initialised, returns current_rsp unchanged.
5. Decrements the current thread’s ticks_remaining; if still > 0, returns unchanged.
6. Saves current_rsp in current_thread.saved_rsp.
7. Pushes the current thread index onto ready_queue (marks it Ready).
8. Pops the front of ready_queue as next_idx. Because we just pushed current, the queue is always non-empty; unwrap_or(current_idx) is only a safety fallback. If current was the only thread it gets re-scheduled.
9. Resets ticks_remaining = QUANTUM_TICKS, marks thread as Running.
10. Returns next_thread.saved_rsp.

The stub then sets RSP = returned value and executes the symmetric pops + iretq, which resumes execution on the new thread.

Initial Stack Layout for New Threads

spawn_thread(entry) allocates a 64 KiB Vec<u8> and writes a fake interrupt frame at the top. The frame is exactly what a preempted thread’s stack looks like, so the same assembly stub can start a new thread as if it were resuming a preempted one.

high address  ┌──────────────────────────┐
              │  SS   = 0                │  ← null selector, valid for ring-0
              │  RSP  = stack_top−8      │  ← thread's initial stack pointer
              │  RFLAGS = 0x202          │  ← bit 9 (IF) + bit 1 (reserved)
              │  CS   = 0x08             │  ← kernel code segment
              │  RIP  = entry            │  ← thread entry point
              ├──────────────────────────┤
              │  rax  = 0                │  15 GPRs (120 bytes)
              │  rbx  = 0                │
              │  …                       │
              │  r15  = 0                │
              ├──────────────────────────┤
              │  FXSAVE area             │  512 bytes (16-byte aligned)
              │  (x87/MMX/SSE state)     │  MXCSR = 0x1F80 at offset +24
              │                          │  XMM0-15 at offset +160
              │                          │  ← saved_rsp points here
low address   └──────────────────────────┘

saved_rsp = base of the 512-byte FXSAVE area. The SwitchFrame (GPRs + iretq frame) sits at saved_rsp + 512. Total region is 672 bytes, guaranteed 16-byte aligned by rounding stack_top down.

Timer Quantum

QUANTUM_TICKS in task/scheduler.rs controls how many LAPIC ticks (1 tick = 1 ms at 1000 Hz) each thread runs before being preempted. The default is 10 (10 ms per thread).

To increase to 50 ms:

#![allow(unused)]
fn main() {
pub const QUANTUM_TICKS: u32 = 50;
}

Thread-safe Async Executor

Global state

TASK_QUEUE and WAIT_MAP use SpinMutex (a spin::Mutex wrapper with deadlock detection). On a single CPU with preemption, a thread can be preempted while holding a spinlock; the new thread spinning on the same lock will waste its quantum and yield back, at which point the original thread releases the lock. If this doesn’t resolve within ~100 ms (SPIN_LIMIT iterations), SpinMutex panics with a serial diagnostic rather than hanging silently.

ISR-safe waker deallocation (WAKER_CACHE)

Both the timer ISR (timer::tick) and the keyboard ISR call Waker::wake(), which consumes the stored Waker. If that were the last Arc<TaskWaker> reference, the Drop impl would call into linked_list_allocator, whose spinlock may already be held by the preempted thread → deadlock.

WAKER_CACHE (Mutex<BTreeMap<TaskId, Waker>>) holds one cached Waker per live task, keeping the Arc strong count ≥ 2 whenever an ISR-accessible copy exists. The ISR’s drop reduces the count from 2 → 1; the cache’s copy is only freed from executor context when a task completes (Poll::Ready).

Task: Send requirement

Task::new requires Future<Output = ()> + Send + 'static. All built-in tasks (timer, keyboard, example) satisfy this because they only hold values that are Send (atomics, Mutex-guarded globals, simple scalars).

spawn(task) and run_worker()

executor::spawn pushes a Task into TASK_QUEUE. executor::run_worker loops:

1. Move tasks whose wakers fired from WAIT_MAP → TASK_QUEUE.
2. Poll every task in TASK_QUEUE. If Pending, move to WAIT_MAP.
3. sleep_if_idle: disable interrupts, check WAKE_QUEUE, then atomically re-enable + HLT (prevents missed-wakeup race).

Locking Rules

The ISR already runs with IF = 0, so it never needs to call without_interrupts.

Deadlock Detection

All spin::Mutex locks have been replaced with SpinMutex (libkernel/src/spin_mutex.rs), which counts spin iterations and panics after a threshold:

On timeout, deadlock_panic() writes directly to serial port 0x3F8 (bypassing SERIAL1’s lock) and then panics. This turns silent hangs into actionable diagnostics.

Demonstrating Preemption

Add a spinning task to confirm no starvation:

#![allow(unused)]
fn main() {
executor::spawn(Task::new(async {
    loop { core::hint::spin_loop(); }
}));
}

Without preemption this would freeze the kernel. With the scheduler, the LAPIC timer fires every 10 ms and rotates to the next thread, so [timer] tick: Ns elapsed still appears every second.

Paging Design

Virtual Address Layout

x86-64 canonical addresses split into two halves:

0x0000_0000_0000_0000 ┐
       ...            │  lower canonical half — user process address space
0x0000_7FFF_FFFF_FFFF ┘
                        (non-canonical gap — any access faults)
0xFFFF_8000_0000_0000   kernel heap        (HEAP_START, 256 KiB)
0xFFFF_8001_0000_0000   Local APIC MMIO   (APIC_BASE, 4 KiB)
0xFFFF_8001_0001_0000   IO APIC(s)        (4 KiB × n, relative to APIC_BASE)
0xFFFF_8002_0000_0000   MMIO window       (MMIO_VIRT_BASE, 512 GiB)
  ↑ PCIe ECAM, virtio BARs, future driver MMIO allocated here
0xFFFF_FF80_0000_0000   recursive PT window (for index 511, see below)
0xFFFF_FFFF_FFFF_F000   PML4 self-mapping   (recursive index 511)
phys_mem_offset         bootloader physical identity map (stays put)
  + all physical RAM

All three kernel allocation regions (heap, APIC, MMIO) share PML4 index 256 (0xFFFF_8000_* through 0xFFFF_80FF_*), keeping the kernel footprint in a single top-level page-table entry — easy to share across per-process page tables without marking it USER_ACCESSIBLE.

Page Table Implementation: RecursivePageTable

Why recursive instead of OffsetPageTable

OffsetPageTable walks page-table frames by computing phys_mem_offset + frame_phys_address. This creates a permanent dependency on the bootloader’s physical-identity map (which lives in the lower canonical half). For user-space isolation we want the lower half to be entirely process-owned.

RecursivePageTable eliminates this dependency: the CPU’s own hardware page walker is used to reach PT frames, so no identity map is needed for page-table operations.

How recursive mapping works

One PML4 slot (index 511) is pointed at the PML4’s own physical frame. When the CPU walks this entry it re-enters the same PML4 as if it were a PDPT. Repeating four times (P4→511, P3→511, P2→511, P1→511) exposes the PML4’s own 4 KiB page at virtual address 0xFFFF_FFFF_FFFF_F000.

The full recursive window for index R (R=511) maps every page-table frame at a computable virtual address:

The x86_64 crate’s RecursivePageTable type uses these computable addresses to implement Mapper and Translate without any identity-map knowledge.

Setup sequence (in libkernel::memory::init)

1. Read CR3 → PML4 physical frame
2. Access PML4 via bootloader identity map: virt = phys_mem_offset + pml4_phys
3. Write PML4[511] = (pml4_phys_frame, PRESENT | WRITABLE)
4. flush_all()   ← new mapping is now active
5. Compute recursive PML4 address: 0xFFFF_FFFF_FFFF_F000
6. Obtain &'static mut PageTable at that address
7. RecursivePageTable::new(pml4_at_recursive_addr)

After step 7 the identity map is still live (bootloader mapping is never removed), but RecursivePageTable does not use it for page-table walks.

MMIO Virtual Address Allocator

Problem with the old approach

The old map_mmio_region mapped MMIO at phys_mem_offset + phys_addr — the same virtual address the identity map uses for regular RAM. This worked but:

• It placed MMIO in the lower canonical half (future user space).
• It gave MMIO a fixed virtual address tied to phys_mem_offset, which varies per boot and can change if the bootloader is swapped.

New design: bump allocator + cache

A bump pointer starts at MMIO_VIRT_BASE = 0xFFFF_8002_0000_0000 and advances one region at a time. A BTreeMap<phys_base, virt_base> cache ensures that mapping the same physical address twice returns the same virtual address.

MMIO_VIRT_BASE  0xFFFF_8002_0000_0000
  + PCIe ECAM    1 MiB
  + virtio BAR0  varies
  + ...
  (grows upward; 512 GiB window — exhaustion is practically impossible)

Flags: PRESENT | WRITABLE | NO_CACHE (same as before).

Cache key

The cache key is the page-aligned physical base address. If the same physical base is mapped twice with different sizes the second call returns the cached mapping (the first mapping covers at least as many pages as were originally requested; in practice PCI BAR sizes are fixed per device).

Heap dependency

BTreeMap::insert allocates from the kernel heap. map_mmio_region must not be called before init_heap completes or from interrupt context. All current call sites (boot path in main.rs, KernelHal::mmio_phys_to_virt) satisfy this constraint.

Remaining Identity Map Dependency

After the switch to RecursivePageTable, the bootloader identity map is still used in exactly two places:

Both are kernel-private and never exposed to user space. The bootloader identity map entries do not have the USER_ACCESSIBLE flag, so they are invisible to ring-3 processes regardless.

The restriction: every page table the kernel uses to walk page structures must keep the bootloader’s PML4 entries for the identity-map region. For per-process page tables this is easily satisfied by copying PML4 entries 0–255 (lower half) from the kernel PML4 — without USER_ACCESSIBLE — at process creation time.

Per-Process Page Tables

Each process gets its own PML4, created by MemoryServices::create_user_page_table:

• Slot 511: self-referential entry pointing to the process’s own PML4 physical frame (required for RecursivePageTable to work per-process).
• Slots 256–510: shared kernel mappings (heap, APIC, MMIO window, physical memory direct map), copied verbatim from the active PML4. These are high-half addresses, never accessible from ring-3. Because the PML4 entries point to the same PDPT/PD/PT frames, changes to kernel page tables at levels below PML4 are automatically visible in all address spaces.
• Slots 0–255: process-private user-space mappings. The process’s code, stack, heap, and memory-mapped files live here.

Switching between processes requires only a mov cr3, new_pml4_phys — the kernel’s high-half mappings are identical in every page table so no TLB flush is needed for kernel entries (on CPUs with PCID support).

PML4 lifecycle

User PML4s and their lower-half page table frames are freed when a process exits (terminate_process) or replaces its address space (execve). The kernel boot PML4 physical address is stored in KERNEL_PML4_PHYS (set during init_services). Before freeing a user PML4, the dying/exec’ing code switches CR3 and the scheduler’s thread record to the kernel PML4. This is critical because the frame allocator uses an intrusive free-list that overwrites freed frames immediately — leaving CR3 pointing at a freed PML4 would cause a triple fault on the next TLB refill.

Files Changed

mmap Phased Design

Overview

This document describes a phased plan for improving the virtual memory management subsystem, starting from the current minimal mmap implementation and building towards file-backed, shared mappings.

Each phase is self-contained and independently testable.

Current State

mmap (syscall 9)

• Anonymous (MAP_ANONYMOUS) and file-backed MAP_PRIVATE (eager copy).
• MAP_FIXED supported — implicit munmap of overlapping VMAs (Linux semantics).
• Non-fixed allocations use a top-down gap finder over the VMA tree ([MMAP_FLOOR, MMAP_CEILING) = [0x10_0000_0000, 0x4000_0000_0000)). Freed regions are automatically reused.
• Pages are eagerly allocated, zeroed, and mapped.
• prot argument is honoured — page table flags are derived from PROT_READ, PROT_WRITE, PROT_EXEC via Vma::page_table_flags().
• Regions are tracked as BTreeMap<u64, Vma> (vma_map in Process).
• /proc/maps displays actual rwxp flags from VMA metadata.

munmap (syscall 11)

Implemented — unmaps pages, frees frames to the free list, and splits/removes VMAs. Supports partial unmaps (front, tail, middle split).

mprotect (syscall 10)

Implemented — updates page table flags and splits/updates VMAs. Supports partial mprotect across VMA boundaries (front, tail, middle split).

Process cleanup on exit

sys_exit frees all user-space frames (ELF segments, brk heap, user stack, mmap regions) and intermediate page table frames before marking zombie.

Process cleanup on execve

sys_execve creates a fresh PML4, switches CR3, then frees the old address space (all user pages and page tables).

Phase 1: VMA Tracking + PROT Flags ✓ (implemented)

Goal: Replace the bare Vec<(u64, u64)> region list with a proper VMA (Virtual Memory Area) structure, and honour the prot argument in mmap.

VMA struct

Add to libkernel/src/process.rs (or a new libkernel/src/vma.rs):

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct Vma {
    pub start: u64,        // page-aligned
    pub len: u64,          // page-aligned
    pub prot: u32,         // PROT_READ | PROT_WRITE | PROT_EXEC
    pub flags: u32,        // MAP_PRIVATE | MAP_ANONYMOUS | MAP_SHARED | ...
    pub fd: Option<usize>, // file descriptor (Phase 5)
    pub offset: u64,       // file offset   (Phase 5)
}
}

Store VMAs in a BTreeMap<u64, Vma> keyed by start address, replacing mmap_regions: Vec<(u64, u64)>.

PROT flag translation

Map Linux PROT_* to x86-64 page table flags:

Apply these flags in alloc_and_map_user_pages instead of the current hardcoded USER_DATA_FLAGS.

Changes

Test

Allocate an mmap region with PROT_READ only, attempt a write from userspace — should page-fault.

Phase 2: Frame Free List + munmap ✓ (implemented)

Goal: Actually free physical frames when munmap is called.

Frame allocator changes

The current frame allocator (BootInfoFrameAllocator wrapping an iterator of usable frames) is allocate-only. Two options:

1. Bitmap allocator — replace the iterator with a bitmap over all usable RAM. Deallocation sets a bit. Simple, O(1) free, but O(n) alloc in the worst case.
2. Free-list overlay — keep the bitmap for the initial boot-time pool, but maintain a singly-linked free list of returned frames (write the next pointer into the first 8 bytes of the freed page via the physical memory map). O(1) alloc and free.

Decision: free-list overlay. The bitmap is needed anyway to know which frames are in use, but a free list on top gives O(1) alloc from returned frames.

Unmap primitive

Add unmap_user_page(pml4_phys, vaddr) -> Option<PhysAddr> to the memory subsystem. This walks the page table, clears the PTE, invokes invlpg, and returns the physical frame address so the caller can free it.

sys_munmap implementation

fn sys_munmap(addr: u64, length: u64) -> i64

1. Page-align addr and length.
2. Look up overlapping VMAs.
3. For each page in the range: call unmap_user_page, push the returned frame onto the free list.
4. Split/remove VMAs as needed (a munmap in the middle of a VMA creates two smaller VMAs).
5. TLB flush (per-page invlpg is fine for now; batch flush can come later).

Changes

Contiguous DMA allocations

alloc_dma_pages(pages) with pages > 1 bypasses the free list and uses allocate_frame_sequential to guarantee physical contiguity. The sequential allocator walks the boot-time memory map and can be exhausted — once next exceeds the total usable frames, it returns None even if the free list has recycled frames available.

In practice this is fine because multi-page contiguous allocations only happen during early boot (VirtIO descriptor rings). If this becomes a problem in the future, options include:

• Fall back to the free list for single-frame DMA when sequential is exhausted.
• Replace the sequential allocator with a buddy allocator that can satisfy contiguous requests from recycled frames.

Test

mmap a region, write a pattern, munmap it, mmap a new region — should get the same (or nearby) frames back, zero-filled.

Phase 3: mprotect + Process Cleanup ✓ (implemented)

Goal: Change page permissions on existing mappings, and free all process memory on exit/execve.

sys_mprotect

fn sys_mprotect(addr: u64, length: u64, prot: u64) -> i64

1. Validate addr is page-aligned.
2. Walk VMAs in the range, update vma.prot.
3. For each page: rewrite the PTE flags to match the new prot (reuse the PROT→PTF translation from Phase 1).
4. invlpg each modified page.
5. May need to split VMAs if the prot change covers only part of a VMA.

Process cleanup on exit

When a process exits (sys_exit / sys_exit_group), before marking zombie:

1. Iterate all VMAs.
2. For each page in each VMA: unmap and free the frame (reuse Phase 2 primitives).
3. Free the user page tables themselves (PML4, PDPT, PD, PT pages).
4. Free the brk region (iterate from brk_base to brk_current).
5. Free the user stack pages.

Process cleanup on execve

sys_execve already creates a fresh PML4. After the new PML4 is set up, free the old page tables and all frames from the old VMA map (same cleanup logic as exit, but targeting the old PML4).

Changes

Test

mmap RW, write data, mprotect to read-only, attempt write — should fault. Run a long-lived process that repeatedly spawns children — memory usage should stay bounded.

Phase 4: MAP_FIXED + Gap Finding ✓ (implemented)

Goal: Support MAP_FIXED placement and smarter allocation that avoids fragmenting the address space.

MAP_FIXED

MAP_FIXED performs implicit munmap of overlapping VMAs before mapping at the requested address (Linux semantics). Addr must be page-aligned and non-zero.

Gap-finding allocator

Replaced the bump-down pointer (mmap_next) with a generic top-down gap finder (libkernel/src/gap.rs). The OccupiedRanges trait abstracts iteration over occupied intervals so the algorithm can be reused.

Search range: [MMAP_FLOOR, MMAP_CEILING) = [0x10_0000_0000, 0x4000_0000_0000). The VMA BTreeMap is the sole source of truth — no bump pointer.

Changes

Phase 5a: File-Backed MAP_PRIVATE (eager copy) ✓ (implemented)

Goal: Support mmap(fd, offset, ...) for MAP_PRIVATE file-backed mappings with eager data copy. No sharing, no refcounting, no writeback.

6th syscall argument

The Linux mmap signature is:

void *mmap(void *addr, size_t length, int prot, int flags, int fd, off_t offset);

fd and offset are the 5th and 6th arguments. The assembly stub saves user R9 to per_cpu.user_r9 (offset 32). sys_mmap reads the offset via libkernel::syscall::get_user_r9() — no ABI change needed.

Design: read from the fd’s buffer

Two approaches were considered:

1. Read from VFS by path — incorrect because a file’s path can change after open (rename, unlink). An open fd refers to an inode, not a path.
2. Read from the fd’s existing in-memory buffer — VfsHandle holds the full file content in a Vec<u8>. Exposed via FileHandle::content_bytes(). Semantically correct: the fd holds a reference to the file content.

Decision: option 2. When lazy/partial sys_open or inode-based VFS arrives later, content_bytes() can trigger a full load or we switch to an inode-keyed page cache. The mmap code doesn’t need to change.

Implementation

• FileHandle::content_bytes() — default returns None.
• VfsHandle::content_bytes() — returns Some(&self.content).
• sys_mmap file-backed path: extracts fd/offset, calls content_bytes(), allocates per-page (clear + copy file data, clamped to file length — bytes past EOF stay zero, matching Linux), maps with prot flags.
• Both MAP_FIXED and non-fixed variants work for file-backed — the address selection logic from Phase 4 is reused.

Changes

Test

mmap_file: opens /shell, reads first 64 bytes via read(), mmaps same file with MAP_PRIVATE/PROT_READ, compares mapped bytes with read() output, munmaps, exits cleanly.

Phase 5b: MAP_SHARED + Refcounted Frames ✓ (anonymous shared memory)

Goal: Support shared anonymous mappings with reference-counted frames.

Shared memory objects (shmem_create)

A custom syscall shmem_create(size) (nr 508) creates a shared memory object backed by eagerly-allocated, zeroed physical frames and returns a file descriptor. The fd can be inherited by child processes or passed via IPC. Both sides call mmap(MAP_SHARED, fd) to map the same physical frames into their address spaces.

Frame refcount table

A BTreeMap<u64, u16> in MemoryServices tracks frames with refcount ≥ 2. Frames not in the table have an implicit refcount of 1 (single owner).

Each shared frame has owners:

1. The SharedMemInner object itself (1 ref, released on Arc drop)
2. Each process mapping (1 ref per mmap, released on munmap or exit)

Methods:

• ref_share(phys) — increment (insert with 2 if new to table)
• ref_release(phys) -> bool — decrement, return true if frame should be freed

Refcount-aware cleanup

• unmap_and_release_user_page() — unmaps PTE, calls ref_release, only frees when refcount reaches 0.
• cleanup_user_address_space() — uses ref_release for all leaf frames. Backwards-compatible: non-shared frames return true immediately.
• SharedMemInner::drop() — calls release_shared_frame() for each backing frame. Safe because Drop only fires from fd close (outside with_memory).

MAP_SHARED in sys_mmap

• Validates MAP_SHARED and MAP_PRIVATE are mutually exclusive
• MAP_SHARED | MAP_ANONYMOUS returns -EINVAL (no fork)
• MAP_SHARED with fd: extracts SharedMemInner from FdObject::SharedMem, maps its physical frames, increments refcounts via ref_share

Changes

Test

user/src/shmem_test.c: Parent creates shmem, writes magic pattern, spawns child. Child inherits fd, mmaps it, verifies pattern, writes response. Parent waits, verifies response.

Phase 5c: File-Backed MAP_SHARED (future)

Goal: Multiple processes mapping the same file share physical frames via an inode-keyed page cache.

This requires:

1. VFS inode identifiers — unique per file across mounts. The 9P protocol carries qid.path which serves as an inode, but it is currently discarded when converting to VfsDirEntry.
2. Shared page cache — a global BTreeMap<(InodeId, page_offset) → PhysAddr> so multiple processes mapping the same file page get the same frame.
3. Dirty tracking — msync or process exit writes dirty shared pages back to the file.

The frame refcount table from Phase 5b provides the foundation.

Dependency Graph

Phase 1 ─── VMA tracking + PROT flags
   │
   ├──▶ Phase 2 ─── Frame free list + munmap
   │       │
   │       └──▶ Phase 3 ─── mprotect + process cleanup
   │               │
   │               └──▶ Phase 4 ─── MAP_FIXED + gap finding
   │                       │
   │                       ├──▶ Phase 5a ─── File-backed MAP_PRIVATE (eager copy)
   │                       │
   │                       └──▶ Phase 5b ─── MAP_SHARED (anonymous, shmem_create)
   │                               │
   │                               └──▶ Phase 5c ─── File-backed MAP_SHARED
   │                                       (requires inode-based VFS + page cache)

Phase 5b (MAP_SHARED anonymous) uses frame refcounting and shmem_create to share physical frames between processes. No VFS changes needed.

Phase 5c (file-backed MAP_SHARED) requires inode identifiers from the VFS and a global page cache, building on Phase 5b’s refcount infrastructure.

Key Decisions

Eager vs demand paging

All phases use eager paging — frames are allocated and mapped immediately in sys_mmap. Demand paging (lazy fault-in) is a future optimisation that does not affect the syscall interface.

6th syscall argument for mmap

The offset parameter (6th arg, user r9) will be read from PerCpuData rather than changing the dispatch function signature. This avoids adding overhead to every syscall for a parameter only mmap uses.

Frame allocator: free-list overlay

Freed frames go onto a singly-linked free list stored in the pages themselves (using the physical memory map for access). The existing boot-time allocator remains for initial allocation; the free list is consulted first.

VMA storage: BTreeMap

A BTreeMap<u64, Vma> keyed by start address provides O(log n) lookup, ordered iteration for gap-finding, and natural support for range queries. Adequate for the expected number of VMAs per process (tens to low hundreds).

Graphics Subsystem Design

Overview

The kernel migrates from VGA text mode (80x25) to a pixel framebuffer during boot. Two hardware paths are covered: the Bochs Graphics Adapter (BGA) for the initial implementation, and virtio-gpu as future work.

After the switch, all existing output (println!, status_bar!, timeline strip, boot progress bar) renders via an 8x16 bitmap font onto the framebuffer. The text grid expands from 80x25 to 128x48 characters at 1024x768 resolution.

Architecture

  Early boot (text mode)          After PCI scan (graphical mode)
  ========================        ================================

  print!/status_bar!              print!/status_bar!
       |                               |
    Writer                          Writer
       |                               |
  DisplayBackend::TextMode        DisplayBackend::Graphical
       |                               |
  VgaBuffer (0xB8000 MMIO)       Framebuffer (BGA LFB MMIO)
                                       |
                                  font::draw_char() -> pixels

The Writer struct contains a DisplayBackend enum that dispatches all cell reads/writes to either the legacy VGA text buffer or the pixel framebuffer. The switch happens once during boot after PCI enumeration detects the BGA device.

BGA (Bochs Graphics Adapter) – Implemented

Hardware Interface

The BGA device is QEMU’s default VGA adapter on Q35 machines (-vga std). It is controlled via two I/O ports:

Register Map

Mode Switch Sequence

1. Write ENABLE = 0 (disable display)
2. Write XRES = 1024, YRES = 768, BPP = 32
3. Write ENABLE = 0x01 | 0x20 (enabled + LFB enabled)

Linear Framebuffer (LFB)

The LFB is located at PCI BAR0 of the BGA device:

• PCI Vendor: 0x1234
• PCI Device: 0x1111
• BAR0: Physical base address of the LFB (typically 0xFD000000 on Q35)
• Size: width * height * (bpp/8) = 1024 * 768 * 4 = 3,145,728 bytes
• Pixel format: BGRX (blue in byte 0, green in byte 1, red in byte 2, byte 3 unused)

The kernel maps the LFB into the kernel MMIO virtual window (0xFFFF_8002_…) using map_mmio_region(). This region is present in all user page tables (via shared PML4 entries 256-510).

Software Text Rendering

Characters are rendered using an embedded 8x16 bitmap font (standard IBM VGA ROM font, CP437 character set, 256 glyphs, 4096 bytes).

• Text grid: 128 columns x 48 rows (1024/8 x 768/16)
• Font: libkernel/src/font.rs – FONT_8X16 static array + draw_char()
• Shadow buffer: [[ScreenChar; 128]; 48] inside DisplayBackend::Graphical enables scrolling without reading back from MMIO

Color Mapping

The VGA 16-color palette is mapped to 32-bit BGRA values:

Row Layout (preserved from text mode)

Scrolling

The graphical backend uses a fast scroll path:

1. Framebuffer::scroll_up() uses core::ptr::copy() to shift pixel data up by one character row (16 scanlines) in a single memcpy operation
2. The shadow cells array is shifted correspondingly
3. Only the new blank bottom row is cleared with fill_rect()

This avoids the naive approach of redrawing every character cell on scroll.

Boot Sequence

1. Kernel boots in VGA text mode – early println! works before PCI scan
2. After PCI scan: detect BGA via I/O port ID register
3. Find BGA PCI device, read BAR0 for LFB physical address
4. Map LFB into kernel virtual space
5. Call bga_set_mode(1024, 768, 32) to switch hardware
6. Call switch_to_framebuffer() – copies current text content into shadow buffer, repaints entire screen
7. All subsequent output renders as pixels

If BGA is not detected (e.g. -vga none), the kernel stays in text mode.

QEMU Configuration

Q35 machine includes stdvga (BGA-compatible) by default. No changes to run.sh required. To be explicit: -vga std.

Limitations

• No hardware cursor in graphical mode (software cursor is a future enhancement)
• LFB mapped with NO_CACHE (not write-combining); acceptable for text console but suboptimal for heavy graphics. A future optimization would configure PAT for write-combining on the LFB region.
• Only works in QEMU/Bochs (BGA is not present on real hardware)

VirtIO-GPU – Future Work

Motivation

• Standard virtio device, works with the virtio-drivers crate already in use
• Supports hardware-accelerated 2D operations (TRANSFER_TO_HOST_2D)
• Better fit for the existing virtio infrastructure (virtio-blk, virtio-9p)
• Portable across any hypervisor supporting virtio-gpu (not just QEMU)

Hardware Interface

Command Protocol

Unlike BGA’s simple I/O port registers, virtio-gpu uses a request/response protocol over virtqueues:

1. RESOURCE_CREATE_2D – allocate a 2D resource (the framebuffer)
2. RESOURCE_ATTACH_BACKING – attach DMA pages as backing store
3. SET_SCANOUT – assign the resource to a display output
4. TRANSFER_TO_HOST_2D – copy dirty rectangles from guest to host
5. RESOURCE_FLUSH – tell the host to display the updated region

Design Sketch

• VirtioGpuActor following the existing VirtioBlkActor pattern
• Scanout = framebuffer resource backed by DMA pages from alloc_dma_pages()
• Periodic TRANSFER_TO_HOST_2D + RESOURCE_FLUSH to update display
• Dirty-rect tracking to minimize transfer size
• Could share the same Framebuffer abstraction used by BGA

Why BGA First

• Simpler: I/O port registers + direct MMIO framebuffer writes
• No virtqueue setup, no command protocol
• QEMU Q35 has it by default (stdvga)
• Sufficient for a text console

Key Files

Status

• BGA detection and mode switching
• Linear framebuffer mapping and pixel rendering
• 8x16 bitmap font (full CP437 character set)
• DisplayBackend abstraction with text-mode fallback
• Fast pixel scrolling
• Status bar, timeline, progress bar all work in graphical mode
• Software cursor (underline/block at cursor position)
• Write-combining for LFB pages (PAT configuration)
• Virtio-GPU backend

FPU / SSE State Management

x86-64 Floating-Point & SIMD Instruction Sets

SSE2 is part of the x86-64 baseline — every long-mode CPU supports it, and the System V AMD64 ABI uses XMM0–XMM7 for floating-point arguments/returns. musl libc is compiled with SSE2 and will use XMM registers in user-space code.

Kernel Target Configuration

The kernel’s custom target (x86_64-os.json) specifies:

"features": "-mmx,-sse,+soft-float"

This tells LLVM to never emit SSE/MMX instructions in kernel Rust code. All floating-point operations (if any) use soft-float emulation. This means the kernel never touches XMM registers, so:

• Syscall path: No SSE save/restore needed — the kernel executes entirely with GPRs, and syscall/sysret returns to the same process.
• Interrupt handlers: Safe as long as they don’t use SSE (guaranteed by the target config).
• Timer preemption: The only path that switches between different user processes’ register contexts — requires SSE save/restore.

CR0/CR4 Setup (enable_sse)

SSE instructions will fault unless the CPU’s control registers are configured:

#![allow(unused)]
fn main() {
pub fn enable_sse() {
    unsafe {
        // CR0: clear EM (bit 2, x87 emulation), set MP (bit 1, monitor coprocessor)
        let mut cr0 = Cr0::read_raw();
        cr0 &= !(1 << 2); // clear CR0.EM
        cr0 |= 1 << 1;    // set CR0.MP
        Cr0::write_raw(cr0);

        // CR4: set OSFXSR (bit 9) and OSXMMEXCPT (bit 10)
        let mut cr4 = Cr4::read_raw();
        cr4 |= (1 << 9) | (1 << 10);
        Cr4::write_raw(cr4);
    }
}
}

• CR0.EM = 0: Do not trap x87/SSE instructions.
• CR0.MP = 1: Enable WAIT/FWAIT monitoring.
• CR4.OSFXSR = 1: Enable FXSAVE/FXRSTOR and SSE instructions.
• CR4.OSXMMEXCPT = 1: Enable unmasked SSE exception handling via #XM.

Called once during boot, before any user processes are spawned.

Eager FXSAVE/FXRSTOR Context Switch

We use the eager strategy: save and restore FPU/SSE state on every timer-driven context switch, unconditionally.

Timer stub flow

interrupt fires → CPU pushes iretq frame (40 bytes)
               → stub pushes 15 GPRs (120 bytes)
               → sub rsp, 512; fxsave [rsp]   ← save SSE state
               → call preempt_tick             ← may switch RSP
               → fxrstor [rsp]                 ← restore SSE state
               → add rsp, 512
               → pop GPRs; iretq

Stack layout during preemption

high address  ┌──────────────────────────┐
              │  SS / RSP / RFLAGS       │  iretq frame (40 bytes)
              │  CS / RIP                │
              ├──────────────────────────┤
              │  rax, rbx, ... r15       │  15 GPRs (120 bytes)
              ├──────────────────────────┤
              │  FXSAVE area             │  512 bytes (16-byte aligned)
              │  (x87/MMX/SSE state)     │  MXCSR at offset +24
              │                          │  XMM0-15 at offset +160
low address   └──────────────────────────┘  ← saved_rsp points here

Total: 672 bytes = 42 x 16, preserving 16-byte alignment for both fxsave (requires 16-byte aligned operand) and the SysV ABI call convention.

New thread initialization

spawn_thread and spawn_user_thread allocate the FXSAVE area below the SwitchFrame and initialize MXCSR at offset +24 to 0x1F80 (the Intel default: all SSE exceptions masked, round-to-nearest mode). XMM registers start zeroed.

FXSAVE Memory Layout (512 bytes)

The MXCSR default value 0x1F80 means:

• Bits 12:7 = 0b111111 — all six SSE exception masks set (no traps)
• Bits 14:13 = 0b00 — round-to-nearest-even
• All exception flags (bits 5:0) cleared

Why Syscalls Don’t Need SSE Saves

The SYSCALL instruction does not change the process — it transitions from ring 3 to ring 0 within the same thread. Since the kernel target has -sse,+soft-float, no kernel code will modify XMM registers. When the syscall handler returns via SYSRETQ, XMM registers still hold the user process’s values.

The timer preemption path is different: it can switch from process A’s context to process B’s context, so process A’s XMM state would be overwritten by process B if not saved.

Future Considerations

Lazy FPU switching (CR0.TS)

Instead of saving/restoring on every context switch, set CR0.TS = 1 after switching away from a thread. The next SSE instruction triggers a #NM (Device Not Available) fault, at which point the handler saves the old thread’s state and loads the new thread’s state, then clears CR0.TS.

Pros: Avoids the 512-byte save/restore overhead when threads don’t use SSE (e.g., kernel threads). Cons: More complex, #NM handler latency, modern CPUs make FXSAVE fast enough that eager switching is preferred (Linux switched to eager in 3.15).

XSAVE for AVX

If AVX support is needed in the future, FXSAVE/FXRSTOR only covers XMM0–XMM15. XSAVE/XRSTOR can save the full YMM/ZMM state, but the save area size varies by CPU (queried via CPUID leaf 0xD). This would require:

1. CPUID.0xD.0:EBX to determine XSAVE area size
2. CR4.OSXSAVE = 1 and XCR0 configuration
3. Dynamic allocation of per-thread XSAVE areas
4. Replace FXSAVE/FXRSTOR with XSAVE/XRSTOR in the timer stub

File Descriptors & Pipes

Design for per-process file descriptor tables, the FileHandle trait, blocking syscalls, and the pipe implementation.

Motivation

The kernel currently has three syscalls: write (hardcoded to stdout/stderr via crate::print!()), exit, and arch_prctl. There is no concept of a file descriptor, no read/close, and no IPC mechanism between user processes.

Adding a proper file descriptor layer enables:

• pipe for parent→child / sibling IPC
• Redirecting stdout/stderr to pipes (shell pipelines)
• Future open/read/write/close for VFS-backed files
• dup2 for fd redirection

Overview

  User process                      Kernel
  ─────────────                     ──────
  write(fd, buf, n)  ──syscall──►  fd_table[fd].write(buf)
                                       │
                         ┌─────────────┼──────────────┐
                         ▼             ▼              ▼
                    ConsoleHandle  PipeWriter     VfsHandle  SharedMem
                    → print!()     → PipeInner    → VFS     → shmem frames
                                       ▲
                         ┌─────────────┘
                         │
  read(fd, buf, n)  ──►  fd_table[fd].read(buf)
                              │
                         PipeReader
                         → PipeInner

Layer 1: FileHandle trait

#![allow(unused)]
fn main() {
/// A kernel object backing an open file descriptor.
///
/// Implementations must be safe to share across threads (the fd table
/// holds `Arc<dyn FileHandle>`).
pub trait FileHandle: Send + Sync {
    /// Read up to `buf.len()` bytes.  Returns the number of bytes read,
    /// or 0 for EOF.  May block the calling thread (see "Blocking" below).
    fn read(&self, buf: &mut [u8]) -> Result<usize, FileError>;

    /// Write up to `buf.len()` bytes.  Returns the number of bytes written.
    /// May block the calling thread.
    fn write(&self, buf: &[u8]) -> Result<usize, FileError>;

    /// Release resources associated with this handle.
    /// Called when the last `Arc` is dropped (i.e. last fd closed).
    fn close(&self) {}

    /// Return a name for downcasting purposes.
    fn kind(&self) -> &'static str;

    /// For directory handles: serialize entries as linux_dirent64 into buf.
    fn getdents64(&self, _buf: &mut [u8]) -> Result<usize, FileError> {
        Err(FileError::NotATty)
    }
}
}

FileError is a structured enum in libkernel::file (using snafu for Display):

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, Snafu)]
pub enum FileError {
    BadFd,           // bad file descriptor
    IsDirectory,     // is a directory
    NotATty,         // inappropriate ioctl for device
    TooManyOpenFiles, // too many open files
}
}

Linux errno numeric codes are defined separately in osl::errno and converted from FileError via errno::file_errno(). This keeps libkernel free of Linux-specific numeric constants.

FileHandle::read/write are synchronous — they return when the operation completes or an error occurs. Blocking is handled at the scheduler level (see below), not via async/await.

Layer 2: Per-process fd table

Add to Process:

#![allow(unused)]
fn main() {
pub struct Process {
    // ... existing fields ...
    pub fd_table: Vec<Option<Arc<dyn FileHandle>>>,
}
}

On process creation, pre-populate fds 0–2:

#![allow(unused)]
fn main() {
fd_table: vec![
    Some(Arc::new(ConsoleHandle)),  // 0: stdin  (read returns EBADF for now)
    Some(Arc::new(ConsoleHandle)),  // 1: stdout
    Some(Arc::new(ConsoleHandle)),  // 2: stderr
],
}

Fd allocation: scan for the first None slot; if none, push a new entry. This matches the POSIX “lowest available fd” rule.

#![allow(unused)]
fn main() {
impl Process {
    pub fn alloc_fd(&mut self, handle: Arc<dyn FileHandle>) -> Result<usize, FileError> {
        for (i, slot) in self.fd_table.iter().enumerate() {
            if slot.is_none() {
                self.fd_table[i] = Some(handle);
                return Ok(i);
            }
        }
        if self.fd_table.len() < MAX_FDS {
            let fd = self.fd_table.len();
            self.fd_table.push(Some(handle));
            Ok(fd)
        } else {
            Err(FileError::TooManyOpenFiles)
        }
    }

    pub fn close_fd(&mut self, fd: usize) -> Result<(), FileError> {
        if fd >= self.fd_table.len() {
            return Err(FileError::BadFd);
        }
        match self.fd_table[fd].take() {
            Some(handle) => { handle.close(); Ok(()) }
            None => Err(FileError::BadFd),
        }
    }

    pub fn get_fd(&self, fd: usize) -> Result<Arc<dyn FileHandle>, FileError> {
        self.fd_table.get(fd)
            .and_then(|slot| slot.clone())
            .ok_or(FileError::BadFd)
    }
}
}

Layer 3: ConsoleHandle

The simplest FileHandle — wraps the existing crate::print!() behaviour:

#![allow(unused)]
fn main() {
pub struct ConsoleHandle {
    pub readable: bool,
}

impl FileHandle for ConsoleHandle {
    fn read(&self, buf: &mut [u8]) -> Result<usize, FileError> {
        if !self.readable {
            return Err(FileError::BadFd);
        }
        Ok(crate::console::read_input(buf))
    }

    fn write(&self, buf: &[u8]) -> Result<usize, FileError> {
        if let Ok(s) = core::str::from_utf8(buf) {
            crate::print!("{}", s);
        }
        Ok(buf.len())
    }

    fn kind(&self) -> &'static str { "console" }
}
}

Layer 4: Blocking syscalls (Option C)

Pipe read and write must block when the buffer is empty or full. Rather than adding async/await to the syscall path, we add a Blocked state to the scheduler.

New thread state

#![allow(unused)]
fn main() {
enum ThreadState {
    Ready,
    Running,
    Blocked,   // ← new
    Dead,
}
}

Blocking API

#![allow(unused)]
fn main() {
/// Block the current thread until `waker` is called.
///
/// Saves the current thread's state as `Blocked` and yields to the
/// scheduler.  Returns when another thread (or ISR) calls
/// `unblock(thread_idx)`.
///
/// Must be called with interrupts disabled.
pub fn block_current_thread() { ... }

/// Move a blocked thread back onto the ready queue.
///
/// Safe to call from ISR context (e.g. a pipe write that wakes a reader).
pub fn unblock(thread_idx: usize) { ... }
}

How blocking works

1. Syscall handler (e.g. sys_read on an empty pipe) calls block_current_thread().
2. The scheduler marks the thread Blocked and context-switches away.
3. preempt_tick never re-queues Blocked threads.
4. When the condition is met (e.g. a writer pushes data into the pipe), the pipe calls unblock(thread_idx).
5. unblock sets the thread to Ready and pushes it onto the ready queue.
6. On the next preemption the thread is scheduled, returns from block_current_thread, and the syscall retries the operation.

Avoiding lost wakeups

The pipe must check the condition and call block_current_thread while holding the pipe’s internal lock. The sequence is:

lock pipe
if buffer_empty:
    register self as waiter (store thread_idx)
    unlock pipe
    block_current_thread()       ← yields here
    goto top                     ← retry after wakeup
else:
    copy data
    wake writer if blocked
    unlock pipe
    return count

The critical property: between checking the condition and blocking, no writer can sneak in — the pipe lock is held. The writer will see the registered waiter and call unblock after releasing the lock.

Layer 5: Pipe

Shared state

#![allow(unused)]
fn main() {
struct PipeInner {
    buf: VecDeque<u8>,
    capacity: usize,               // default 4096
    reader_closed: bool,
    writer_closed: bool,
    blocked_reader: Option<usize>,  // thread_idx waiting for data
    blocked_writer: Option<usize>,  // thread_idx waiting for space
}

pub struct Pipe {
    inner: Mutex<PipeInner>,
}
}

Read end

#![allow(unused)]
fn main() {
pub struct PipeReader(Arc<Pipe>);

impl FileHandle for PipeReader {
    fn read(&self, buf: &mut [u8]) -> Result<usize, FileError> {
        loop {
            let mut inner = self.0.inner.lock();
            if !inner.buf.is_empty() {
                let n = inner.drain_to(buf);
                // Wake blocked writer if there's now space.
                if let Some(writer) = inner.blocked_writer.take() {
                    scheduler::unblock(writer);
                }
                return Ok(n);
            }
            if inner.writer_closed {
                return Ok(0); // EOF
            }
            // Buffer empty, writer alive — block.
            inner.blocked_reader = Some(scheduler::current_thread_idx());
            drop(inner);
            scheduler::block_current_thread();
            // Woken up — retry.
        }
    }

    fn write(&self, _buf: &[u8]) -> Result<usize, FileError> {
        Err(FileError::EBADF)
    }

    fn close(&self) {
        let mut inner = self.0.inner.lock();
        inner.reader_closed = true;
        // Wake blocked writer so it sees EPIPE.
        if let Some(writer) = inner.blocked_writer.take() {
            scheduler::unblock(writer);
        }
    }
}
}

Write end

#![allow(unused)]
fn main() {
pub struct PipeWriter(Arc<Pipe>);

impl FileHandle for PipeWriter {
    fn read(&self, _buf: &mut [u8]) -> Result<usize, FileError> {
        Err(FileError::EBADF)
    }

    fn write(&self, buf: &[u8]) -> Result<usize, FileError> {
        let mut offset = 0;
        while offset < buf.len() {
            let mut inner = self.0.inner.lock();
            if inner.reader_closed {
                return Err(FileError::EPIPE);
            }
            let space = inner.capacity - inner.buf.len();
            if space > 0 {
                let n = core::cmp::min(space, buf.len() - offset);
                inner.buf.extend(&buf[offset..offset + n]);
                offset += n;
                // Wake blocked reader.
                if let Some(reader) = inner.blocked_reader.take() {
                    scheduler::unblock(reader);
                }
            } else {
                // Buffer full — block.
                inner.blocked_writer = Some(scheduler::current_thread_idx());
                drop(inner);
                scheduler::block_current_thread();
            }
        }
        Ok(buf.len())
    }

    fn close(&self) {
        let mut inner = self.0.inner.lock();
        inner.writer_closed = true;
        // Wake blocked reader so it sees EOF.
        if let Some(reader) = inner.blocked_reader.take() {
            scheduler::unblock(reader);
        }
    }
}
}

Creating a pipe

#![allow(unused)]
fn main() {
pub fn new_pipe(capacity: usize) -> (PipeReader, PipeWriter) {
    let pipe = Arc::new(Pipe {
        inner: Mutex::new(PipeInner {
            buf: VecDeque::with_capacity(capacity),
            capacity,
            reader_closed: false,
            writer_closed: false,
            blocked_reader: None,
            blocked_writer: None,
        }),
    });
    (PipeReader(pipe.clone()), PipeWriter(pipe))
}
}

Layer 6: Syscall wiring

New syscalls

sys_pipe implementation

#![allow(unused)]
fn main() {
fn sys_pipe(fds_ptr: u64) -> i64 {
    // Validate user pointer (2 × i32 = 8 bytes).
    const USER_LIMIT: u64 = 0x0000_8000_0000_0000;
    if fds_ptr == 0 || fds_ptr + 8 > USER_LIMIT {
        return FileError::EFAULT.0;
    }

    let (reader, writer) = new_pipe(4096);
    let pid = process::current_pid();
    let (read_fd, write_fd) = process::with_process(pid, |proc| {
        let rfd = proc.alloc_fd(Arc::new(reader))?;
        match proc.alloc_fd(Arc::new(writer)) {
            Ok(wfd) => Ok((rfd, wfd)),
            Err(e) => { proc.close_fd(rfd).ok(); Err(e) }
        }
    }).unwrap_or(Err(FileError::EBADF))?;

    // Write fds to user space.
    let fds = fds_ptr as *mut [i32; 2];
    unsafe { (*fds) = [read_fd as i32, write_fd as i32]; }
    0
}
}

Refactored sys_write

#![allow(unused)]
fn main() {
fn sys_write(fd: u64, buf: u64, count: u64) -> i64 {
    // ... existing user pointer validation ...
    let bytes = validated_user_slice(buf, count)?;
    let pid = process::current_pid();
    let handle = process::with_process_ref(pid, |p| {
        p.fd_table.get(fd as usize).and_then(|s| s.clone())
    }).flatten().ok_or(FileError::EBADF)?;
    match handle.write(bytes) {
        Ok(n) => n as i64,
        Err(e) => e.0,
    }
}
}

Implementation order

Phases 1–5 are useful independently — they give user processes a real fd abstraction for stdout/stderr. Phase 6 is needed for any future blocking syscall (futex, sleep, waitpid). Phases 7–8 deliver pipes.

Open questions

• Pipe capacity: 4096 bytes matches Linux’s historical default. Should this be page-sized for alignment, or is VecDeque fine?
• Multiple readers/writers: This design supports only one blocked reader and one blocked writer. For a single pipe between two processes this is fine, but dup-ed fds sharing a pipe end would need a wait queue.
• Signal delivery: POSIX SIGPIPE on write to a broken pipe is not modelled — we return EPIPE instead. Signals can be added later.
• O_NONBLOCK: Not yet supported. Would return EAGAIN instead of blocking. Requires fd-level flags.
• VFS integration: A future VfsHandle implementing FileHandle would connect the VFS’s async read_file to the synchronous FileHandle::read by using the same blocking mechanism.

Actor System

Overview

The kernel uses a lightweight actor model for device drivers and long-running system services. Each actor is an async task that owns its state behind an Arc, receives typed messages through a Mailbox, and responds to requests via one-shot Reply channels.

The design avoids shared mutable state and lock contention between drivers: all cross-actor communication is by message passing.

Core Primitives

Mailbox<M> — libkernel::task::mailbox

An async, mutex-backed message queue.

sender                         receiver (actor run loop)
──────                         ────────────────────────
mailbox.send(msg)         →    while let Some(msg) = inbox.recv().await { ... }
                               (suspends when queue empty; woken on send)
mailbox.close()           →    recv() drains remaining msgs, then returns None

Key properties:

• send acquires the lock, checks closed, and either enqueues the message or drops it immediately. Dropping a message also drops any embedded Reply, which closes the reply channel and unblocks the sender with None.
• close sets closed = true under the lock and wakes the receiver. Messages already in the queue are not removed — recv delivers them before returning None. Any send arriving after close is silently dropped.
• reopen clears the closed flag, used when restarting a driver.
• The mutex makes send and close atomic with respect to each other, eliminating the race between “is it closed?” and “enqueue”.

recv uses a double-check pattern to avoid missed wakeups:

poll():
  lock → dequeue / check closed → unlock   (fast path)
  register waker
  lock → dequeue / check closed → unlock   (second check)
  → Pending

The lock is always released before registering the waker and before waking it, so a send or close that arrives between the two checks will either be seen by the second check or will wake the (now-registered) waker.

Reply<T> — one-shot response channel

Reply<T> is the sending half of a request/response pair.

#![allow(unused)]
fn main() {
// Actor receives:
ActorMsg::Info(reply) => reply.send(ActorStatus { name: "dummy", running: true, info: () }),

// Sender awaits:
let status: Option<ActorStatus<()>> = inbox.ask(|r| ActorMsg::Info(r)).await;
}

Reply::new() returns (Reply<T>, Arc<Mailbox<T>>). The actor calls reply.send(value) to deliver a response; the Drop impl calls close() on the inner mailbox regardless, so the receiver always unblocks:

• reply.send(value) → value pushed, then Reply dropped → close() called. close() does not drain the queue, so the value is still there for recv.
• reply dropped without send → close() called on an empty mailbox → recv() returns None.

ActorMsg<M, I> — the envelope type

Every actor mailbox is Mailbox<ActorMsg<M, I>> where M is the actor-specific message type and I is the actor-specific info detail type (defaults to ()).

#![allow(unused)]
fn main() {
pub enum ActorMsg<M, I: Send = ()> {
    /// Typed info request — reply carries ActorStatus<I> with the full detail.
    Info(Reply<ActorStatus<I>>),
    /// Type-erased info request from the process registry — reply carries
    /// ActorStatus<ErasedInfo> so callers can display detail without knowing I.
    ErasedInfo(Reply<ActorStatus<ErasedInfo>>),
    /// An actor-specific message.
    Inner(M),
}
}

ActorStatus<I> is the response to both info variants:

#![allow(unused)]
fn main() {
pub struct ActorStatus<I = ()> {
    pub name:    &'static str,
    pub running: bool,   // always true when the actor is responding
    pub info:    I,      // actor-specific detail
}
}

ErasedInfo is a type alias for the boxed detail used in type-erased queries:

#![allow(unused)]
fn main() {
pub type ErasedInfo = Box<dyn core::fmt::Debug + Send>;
}

RecvTimeout<M> — timed receive

recv_timeout races the inbox against a Delay, returning whichever fires first:

#![allow(unused)]
fn main() {
pub enum RecvTimeout<M> {
    Message(M),  // a message arrived before the deadline
    Closed,      // mailbox was closed (actor should exit)
    Elapsed,     // timer fired before any message
}

// Usage:
match inbox.recv_timeout(ticks).await {
    RecvTimeout::Message(msg) => { /* handle */ }
    RecvTimeout::Closed       => break,
    RecvTimeout::Elapsed      => { /* periodic work */ }
}
}

Used internally by the #[on_tick] generated run loop.

ask — the request/response pattern

#![allow(unused)]
fn main() {
// Returns Option<R>; None if the actor is stopped or dropped the reply.
let result = inbox.ask(|reply| ActorMsg::Inner(MyMsg::GetThing(reply))).await;
}

ask creates a Reply, wraps it in a message, sends it, and awaits the response. Because a closed mailbox drops incoming messages (and their Replys), ask on a stopped actor returns None immediately rather than hanging.

Self-query deadlock: an actor must never use ask (or registry::ask_info) to query its own mailbox from within a message handler — it cannot recv() the response while blocked executing the current message. Detect self-queries by comparing names and respond directly instead.

Driver Lifecycle — devices::task_driver

DriverTask trait

#![allow(unused)]
fn main() {
pub trait DriverTask: Send + Sync + 'static {
    type Message: Send;
    type Info:    Send + 'static;
    fn name(&self) -> &'static str;
    fn run(
        handle: Arc<Self>,
        stop:   StopToken,
        inbox:  Arc<Mailbox<ActorMsg<Self::Message, Self::Info>>>,
    ) -> impl Future<Output = ()> + Send;
}
}

type Info is the actor-specific detail returned by #[on_info]. Use () if the actor has no custom info.

The run future is 'static because all state is accessed through Arc<Self>. StopToken can be polled between messages for cooperative stop, though most actors simply let inbox.recv() return None (which happens when the mailbox is closed by stop()).

TaskDriver<T> — the lifecycle wrapper

TaskDriver<T> implements Driver (the registry interface) and owns:

Lifecycle:

TaskDriver::new()
  inbox starts CLOSED → sends before start() are dropped immediately

start()
  inbox.reopen()          opens the mailbox
  running = true
  spawn(async { T::run(handle, stop, inbox).await; running = false; })

stop()
  stop_flag = true        StopToken fires
  inbox.close()           recv() will return None after draining

(run loop exits)
  running = false

TaskDriver::new returns (TaskDriver<T>, Arc<Mailbox<ActorMsg<T::Message, T::Info>>>). The caller holds onto the Arc<Mailbox> to send actor-specific messages and registers it in the process registry (see below).

The #[actor] Macro — devices_macros

The macro generates a complete DriverTask implementation from an annotated impl block, eliminating the run-loop boilerplate. All attributes are passthrough no-ops when used outside an #[actor] block.

Basic usage — pure message actor

#![allow(unused)]
fn main() {
pub enum DummyMsg { SetInterval(u64) }

#[derive(Debug)]
pub struct DummyInfo { pub interval_secs: u64 }

pub struct Dummy { interval_secs: AtomicU64 }

#[actor("dummy", DummyMsg)]
impl Dummy {
    #[on_info]
    async fn on_info(&self) -> DummyInfo {
        DummyInfo { interval_secs: self.interval_secs.load(Ordering::Relaxed) }
    }

    #[on_message(SetInterval)]
    async fn set_interval(&self, secs: u64) {
        self.interval_secs.store(secs, Ordering::Relaxed);
    }
}
}

What the macro generates:

#![allow(unused)]
fn main() {
// Inherent impl with handler methods (attributes stripped):
impl Dummy {
    async fn on_info(&self) -> DummyInfo { ... }
    async fn set_interval(&self, secs: u64) { ... }
}

// DriverTask impl with the generated run loop:
impl DriverTask for Dummy {
    type Message = DummyMsg;
    type Info    = DummyInfo;
    fn name(&self) -> &'static str { "dummy" }

    async fn run(handle: Arc<Self>, _stop: StopToken,
                 inbox: Arc<Mailbox<ActorMsg<DummyMsg, DummyInfo>>>) {
        log::info!("[dummy] started");
        while let Some(msg) = inbox.recv().await {
            match msg {
                ActorMsg::Info(reply) =>
                    reply.send(ActorStatus { name: "dummy", running: true,
                                            info: handle.on_info().await }),
                ActorMsg::ErasedInfo(reply) =>
                    reply.send(ActorStatus { name: "dummy", running: true,
                                            info: Box::new(handle.on_info().await) }),
                ActorMsg::Inner(msg) => match msg {
                    DummyMsg::SetInterval(secs) => handle.set_interval(secs).await,
                }
            }
        }
        log::info!("[dummy] stopped");
    }
}

// Convenience type alias (struct name + "Driver"):
pub type DummyDriver = TaskDriver<Dummy>;
}

Any methods in the #[actor] block that have no actor attribute are emitted unchanged in the inherent impl and are callable from handler methods.

#[on_start] — actor startup hook

Called once, after the [actor] started log line and before the message loop:

#![allow(unused)]
fn main() {
#[on_start]
async fn on_start(&self) {
    println!();
    print!("myactor> ");
}
}

Only one #[on_start] method is allowed per actor.

#[on_info] — custom actor info

Without #[on_info], Info and ErasedInfo reply with info: (). Annotate one method to provide actor-specific detail:

#![allow(unused)]
fn main() {
#[on_info]
async fn on_info(&self) -> MyInfo {
    MyInfo { /* fields from self */ }
}
}

The return type must implement Debug + Send. The macro infers type Info = MyInfo and generates both Info and ErasedInfo arms automatically.

#[on_message(Variant)] — inner message handler

Maps one enum variant of the actor’s message type to an async handler:

#![allow(unused)]
fn main() {
#[on_message(DoThing)]
async fn do_thing(&self, n: u32) { ... }
}

The generated match arm is:

#![allow(unused)]
fn main() {
ActorMsg::Inner(MyMsg::DoThing(n)) => handle.do_thing(n).await,
}

Multiple #[on_message] methods are allowed, one per variant.

#[on_tick] — periodic callback

When present, the macro switches to a unified poll_fn loop (see below) that races the inbox against a Delay. The actor must also provide a plain tick_interval_ticks(&self) -> u64 method (no attribute needed):

#![allow(unused)]
fn main() {
fn tick_interval_ticks(&self) -> u64 {
    self.interval_secs.load(Ordering::Relaxed) * TICKS_PER_SECOND
}

#[on_tick]
async fn heartbeat(&self) {
    log::info!("[myactor] tick");
}
}

Only one #[on_tick] method is allowed per actor. The delay is reset after each tick so tick_interval_ticks can change dynamically.

#[on_stream(factory)] — interrupt/hardware stream source

Actors that need to react to hardware events (interrupts, async streams) use #[on_stream]. The factory argument names a plain method that returns a Stream + Unpin; the handler is called for each item:

#![allow(unused)]
fn main() {
// Factory — called once when the actor starts:
fn key_stream(&self) -> KeyStream { KeyStream::new() }

// Handler — called for each item from the stream:
#[on_stream(key_stream)]
async fn on_key(&self, key: Key) {
    // process key event
}
}

Multiple #[on_stream] methods are allowed, one per stream.

The unified poll_fn loop

When one or more #[on_stream] or #[on_tick] attributes are present the macro generates a loop that races all event sources in a single poll_fn:

#![allow(unused)]
fn main() {
// Streams initialised once before the loop:
let mut _stream_0 = handle.key_stream();
// Timer initialised if #[on_tick] is present:
let mut _delay = Delay::new(handle.tick_interval_ticks());

loop {
    enum _Event {
        _Inbox(ActorMsg<KeyboardMsg, KeyboardInfo>),
        _Stream0(Key),   // one variant per #[on_stream]
        _Tick,           // present if #[on_tick]
        _Stopped,
    }
    let mut _recv = inbox.recv();
    let _ev = poll_fn(|cx| {
        // Streams polled first — interrupt-driven, lowest latency:
        match poll_stream_next(&mut _stream_0, cx) {
            Poll::Ready(Some(item)) => return Poll::Ready(_Event::_Stream0(item)),
            Poll::Ready(None)       => return Poll::Ready(_Event::_Stopped),
            Poll::Pending           => {}
        }
        // Inbox — control messages and stop signal:
        match Pin::new(&mut _recv).poll(cx) {
            Poll::Ready(Some(msg)) => return Poll::Ready(_Event::_Inbox(msg)),
            Poll::Ready(None)      => return Poll::Ready(_Event::_Stopped),
            Poll::Pending          => {}
        }
        // Timer (lowest priority):
        if let Poll::Ready(()) = Pin::new(&mut _delay).poll(cx) {
            return Poll::Ready(_Event::_Tick);
        }
        Poll::Pending
    }).await;

    match _ev {
        _Event::_Stopped         => break,
        _Event::_Inbox(msg)      => match msg { /* Info, ErasedInfo, Inner arms */ }
        _Event::_Stream0(key)    => handle.on_key(key).await,
        _Event::_Tick            => {
            handle.heartbeat().await;
            _delay = Delay::new(handle.tick_interval_ticks());
        }
    }
}
}

All wakers (mailbox AtomicWaker, stream AtomicWaker, timer WAKERS slot) register the same task waker, so whichever source fires first reschedules the task. No extra task or thread is needed.

Using #[actor] outside the devices crate

The macro generates impl crate::task_driver::DriverTask for … and pub type XDriver = crate::task_driver::TaskDriver<X>;. In the devices crate this resolves naturally. For crates that use devices as a dependency (e.g. kernel), expose task_driver at the crate root:

#![allow(unused)]
fn main() {
// kernel/src/task_driver.rs
pub use devices::task_driver::*;

// kernel/src/main.rs
pub mod task_driver;   // makes crate::task_driver resolve for #[actor] expansions
}

The generated type alias uses the struct name suffixed with Driver: KeyboardActor → KeyboardActorDriver, Shell → ShellDriver.

Process Registry — libkernel::task::registry

The registry maps actor names to their mailboxes, allowing any code to send messages to a named actor without holding a direct reference.

#![allow(unused)]
fn main() {
// Registration (at init time, in main.rs):
registry::register("dummy", dummy_inbox.clone());

// Typed lookup (when the caller knows both message and info types):
let inbox: Arc<Mailbox<ActorMsg<DummyMsg, DummyInfo>>> =
    registry::get::<DummyMsg, DummyInfo>("dummy")?;
inbox.send(ActorMsg::Inner(DummyMsg::SetInterval(5)));

// Type-erased info query (no knowledge of M or I needed):
if let Some(status) = registry::ask_info("dummy").await {
    println!("name: {}  running: {}  info: {:?}", status.name, status.running, status.info);
}
}

Each registry entry stores two representations of the same mailbox:

Informable is a simple object-safe trait:

#![allow(unused)]
fn main() {
pub trait Informable: Send + Sync {
    fn send_info(&self, reply: Reply<ActorStatus<ErasedInfo>>);
}
// Blanket impl for all actor mailboxes:
impl<M: Send, I: Send + 'static> Informable for Mailbox<ActorMsg<M, I>> {
    fn send_info(&self, reply: Reply<ActorStatus<ErasedInfo>>) {
        self.send(ActorMsg::ErasedInfo(reply));
    }
}
}

ask_info clones the Arc<dyn Informable> while holding the registry lock, drops the lock, then sends the request and awaits the reply — the lock is never held across an await.

Actors in Practice

Shell — pure message actor with startup hook

#![allow(unused)]
fn main() {
pub enum ShellMsg { KeyLine(String) }
pub struct Shell;

#[actor("shell", ShellMsg)]
impl Shell {
    #[on_start]
    async fn on_start(&self) {
        println!();
        print!("ostoo> ");
    }

    #[on_message(KeyLine)]
    async fn on_key_line(&self, line: String) {
        self.execute_command(&line).await;
        print!("ostoo> ");
    }

    // Plain helpers — land in the inherent impl:
    async fn execute_command(&self, line: &str) { ... }
    async fn cmd_driver(&self, rest: &str) { ... }
}
}

The shell prints its prompt in #[on_start] (once, when the actor starts) and again after each command in #[on_message(KeyLine)].

Fire-and-forget dispatch: the keyboard actor sends ShellMsg::KeyLine with mailbox.send() (no reply), so it never blocks waiting for the shell. The shell processes one command at a time; new lines queue in the mailbox.

Self-query avoidance: driver info shell from within a shell command would deadlock if it sent ErasedInfo to the shell’s own mailbox (the shell is busy executing the command and cannot recv). The handler detects the name "shell" and responds directly without going through the registry.

Keyboard — stream actor

#![allow(unused)]
fn main() {
pub struct KeyboardActor {
    keys_processed:   AtomicU64,
    lines_dispatched: AtomicU64,
    line:             spin::Mutex<LineBuf>,
}

#[actor("keyboard", KeyboardMsg)]
impl KeyboardActor {
    fn key_stream(&self) -> KeyStream { KeyStream::new() }

    #[on_stream(key_stream)]
    async fn on_key(&self, key: Key) {
        // buffer characters; dispatch complete lines to shell via send()
    }

    #[on_info]
    async fn on_info(&self) -> KeyboardInfo { ... }
}
}

KeyStream is interrupt-driven: every PS/2 scancode IRQ pushes into a lock-free queue and wakes an AtomicWaker. Because both the stream waker and the inbox waker register the same task waker, the actor sleeps in a single poll_fn and wakes on whichever event arrives first.

The line buffer lives in the actor struct behind a spin::Mutex<LineBuf> so it is accessible from the &self reference in on_key. The mutex is never held across an .await.

Dummy — tick actor (example / test driver)

#![allow(unused)]
fn main() {
#[actor("dummy", DummyMsg)]
impl Dummy {
    fn tick_interval_ticks(&self) -> u64 {
        self.interval_secs.load(Ordering::Relaxed) * TICKS_PER_SECOND
    }

    #[on_tick]
    async fn heartbeat(&self) {
        log::info!("[dummy] heartbeat");
    }

    #[on_info]
    async fn on_info(&self) -> DummyInfo { ... }

    #[on_message(SetInterval)]
    async fn set_interval(&self, secs: u64) { ... }
}
}

Starts stopped. driver start dummy from the shell opens its mailbox and spawns the run loop. driver dummy set-interval 3 sends SetInterval(3) and changes the heartbeat rate at runtime.

Startup Sequence

#![allow(unused)]
fn main() {
// main.rs (abridged)

// Dummy driver — starts stopped, user can start it from the shell
let (dummy_driver, dummy_inbox) = DummyDriver::new(Dummy::new());
devices::driver::register(Box::new(dummy_driver));
registry::register("dummy", dummy_inbox);

// Shell actor — started immediately
let (shell_driver, shell_inbox) = ShellDriver::new(Shell::new());
devices::driver::register(Box::new(shell_driver));
registry::register("shell", shell_inbox.clone());
devices::driver::start_driver("shell").ok();   // reopen + spawn run loop

// Keyboard actor — started immediately, stream-driven by PS/2 IRQs
let (kb_driver, kb_inbox) =
    KeyboardActorDriver::new(KeyboardActor::new());
devices::driver::register(Box::new(kb_driver));
registry::register("keyboard", kb_inbox);
devices::driver::start_driver("keyboard").ok();
}

File Map

virtio-blk Block Device Driver

Overview

The kernel includes a PCI virtio-blk driver that provides read/write access to a QEMU virtual disk. The driver is implemented using the virtio-drivers crate (v0.13) and integrates with the existing actor/driver framework.

The driver is started automatically at boot if a virtio-blk PCI device is found. It is accessible from the shell via the blk commands.

Architecture

QEMU virtio-blk device (PCIe, Q35 ECAM)
        │
        │  PciTransport (virtio-drivers)
        ▼
  VirtIOBlk<KernelHal, PciTransport>   ← virtio protocol implementation
        │
  spin::Mutex (actor + ISR safe)
        │
  VirtioBlkActor                        ← actor framework wrapper
        │
  Mailbox<ActorMsg<VirtioBlkMsg, VirtioBlkInfo>>
        │
  Shell / other actors                  ← consumers

Components

devices/src/virtio/mod.rs — HAL and transport

KernelHal

Implements the virtio_drivers::Hal unsafe trait, bridging the virtio-drivers crate into the kernel memory model:

ECAM / PciRoot

The Q35 machine exposes a PCIe Extended Configuration Access Mechanism (ECAM) region at physical address 0xB000_0000 (1 MiB, covering bus 0).

Physical 0xB000_0000  →  Virtual phys_mem_offset + 0xB000_0000

The mapping is created once during libkernel_main by calling MemoryServices::map_mmio_region. The resulting virtual base is stored in the ECAM_VIRT_BASE atomic and used by create_pci_root() which constructs a PciRoot<MmioCam<'static>> for the virtio-drivers transport layer. (In virtio-drivers 0.13, PciRoot is generic over a ConfigurationAccess implementation; MmioCam wraps the raw MMIO pointer with a Cam::Ecam mode.)

create_pci_transport (formerly create_blk_transport)

#![allow(unused)]
fn main() {
pub fn create_pci_transport(bus: u8, device: u8, function: u8) -> Option<PciTransport>
}

Wraps PciTransport::new::<KernelHal, _>, isolating virtio-drivers from the kernel binary — the kernel crate does not depend on virtio-drivers directly. Works for any virtio-pci device (blk, 9p, etc.), not just block devices. create_blk_transport is kept as a legacy alias.

register_blk_irq

#![allow(unused)]
fn main() {
pub fn register_blk_irq(handler: fn()) -> Option<u8>
}

Registers a dynamic IDT handler for the virtio-blk interrupt (delegating to libkernel::interrupts::register_handler). Returns the allocated IDT vector, which must be programmed into the device’s MSI or IO APIC routing table. IRQ-driven completion is not yet wired up (see Limitations).

devices/src/virtio/blk.rs — the actor

Messages

#![allow(unused)]
fn main() {
pub enum VirtioBlkMsg {
    Read(u64, Reply<Result<Vec<u8>, ()>>),   // sector, reply
    Write(u64, Vec<u8>, Reply<Result<(), ()>>), // sector, data, reply
}
}

Info

#![allow(unused)]
fn main() {
#[derive(Debug)]
pub struct VirtioBlkInfo {
    pub capacity_sectors: u64,
    pub reads:  u64,
    pub writes: u64,
}
}

Returned by driver info virtio-blk and blk info.

VirtioBlkActor

Owns a spin::Mutex<VirtIOBlk<KernelHal, PciTransport>>. The mutex is needed because both the actor task and (future) interrupt handler may access the device.

unsafe impl Send + Sync are required because VirtIOBlk contains raw DMA buffer pointers, which are not auto-Send. Access is always serialised through the spin::Mutex.

Read/write flow

on_read(sector, reply):
  1. lock device → read_blocks_nb(sector, &mut req, buf, &mut resp) → token
  2. unlock device
  3. CompletionFuture.await  (busy-polls peek_used until the device signals done)
  4. lock device → complete_read_blocks(token, &req, buf, &resp)
  5. unlock device
  6. reply.send(Ok(buf))

Write is symmetric with write_blocks_nb / complete_write_blocks.

All of read_blocks_nb, write_blocks_nb, complete_read_blocks, and complete_write_blocks are unsafe fn in virtio-drivers — the safety contract is that the buffers remain valid and unpinned for the duration of the I/O. Because buf, req, and resp all live in the async state machine on the heap, they are not moved or dropped between submit and complete.

CompletionFuture

#![allow(unused)]
fn main() {
struct CompletionFuture<'a> {
    device: &'a spin::Mutex<VirtIOBlk<KernelHal, PciTransport>>,
}

impl Future for CompletionFuture<'_> {
    type Output = ();
    fn poll(...) -> Poll<()> {
        if device.lock().peek_used().is_some() {
            Poll::Ready(())
        } else {
            cx.waker().wake_by_ref();   // reschedule immediately (busy-poll)
            Poll::Pending
        }
    }
}
}

This is a busy-poll future for MVP. It re-schedules itself every executor turn until the virtqueue returns a used buffer. See Limitations for the planned IRQ-driven replacement.

libkernel/src/memory/mod.rs — supporting APIs

Three methods were added to MemoryServices for virtio support:

map_mmio_region(phys_start, size) -> VirtAddr

Maps a physical MMIO range into the linear physical-memory window (phys_mem_offset + phys_start) using 4 KiB pages with PRESENT | WRITABLE | NO_CACHE flags.

Pages already mapped as 4 KiB pages are skipped silently (Ok(_)). Pages inside a 2 MiB or 1 GiB huge-page entry are also skipped (Err(TranslateError::ParentEntryHugePage)) — they are already accessible because the bootloader maps all physical RAM using 2 MiB huge pages.

This huge-page check was the fix for the map_to failed: ParentEntryHugePage panic that occurred when mapping the ECAM region.

alloc_dma_pages(pages) -> Option<PhysAddr>

Allocates pages physically-contiguous 4 KiB frames from the BootInfoFrameAllocator. Panics if frames are not contiguous (very unlikely with the sequential allocator).

translate_virt(virt) -> Option<PhysAddr>

Walks the active RecursivePageTable to find the physical address for any virtual address, regardless of page size (4 KiB, 2 MiB, or 1 GiB).

This is used by KernelHal::share to convert heap buffer addresses to physical addresses. A simple vaddr - phys_mem_offset subtraction would be wrong for heap buffers (which live at HEAP_START, not in the linear physical window), producing garbage physical addresses and causing QEMU to report virtio: zero sized buffers are not allowed.

Boot Sequence

libkernel_main()
  1. memory::init_services(mapper, frame_allocator, phys_mem_offset, map)
  2. map_mmio_region(0xB000_0000, 1 MiB)   ← ECAM
     virtio::set_ecam_base(ecam_virt)
  3. devices::pci::init()                   ← scan CF8/CFC config space
  4. find_devices(0x1AF4, 0x1042)           ← probe modern-transitional first
     find_devices(0x1AF4, 0x1001)           ← then legacy
  5. virtio::create_pci_transport(bus, dev, func)
       └─ PciRoot::new(MmioCam::new(ECAM_VIRT_BASE, Cam::Ecam))
          PciTransport::new::<KernelHal, _>(&mut root, df)
  6. VirtioBlkActor::new(transport)
  7. VirtioBlkActorDriver::new(actor)
  8. driver::register + registry::register("virtio-blk", inbox)
  9. driver::start_driver("virtio-blk")
     → "[kernel] virtio-blk registered"

Shell Commands

Running with a Disk

# Create a blank 64 MiB disk image (once):
make disk

# Build and run with the disk attached:
make run

The run target adds:

-drive file=disk.img,format=raw,if=none,id=hd0
-device virtio-blk-pci,drive=hd0

The kernel uses a Q35 machine (-machine q35) which provides native PCIe and ECAM support.

To run without a disk (e.g. for quick boot tests):

make run-nodisk

PCI Device IDs

Both are probed at boot; modern-transitional is tried first.

Key Files

Limitations

Busy-poll completion

CompletionFuture re-schedules itself every executor turn, consuming CPU until the device completes I/O. The intended replacement is an AtomicWaker-based future that sleeps until the IRQ handler calls wake():

#![allow(unused)]
fn main() {
static IRQ_WAKER: AtomicWaker = AtomicWaker::new();

fn virtio_blk_irq_handler() {
    IRQ_PENDING.store(true, Ordering::Release);
    IRQ_WAKER.wake();
}
}

This requires programming the device’s MSI capability or IO APIC routing with the vector returned by register_blk_irq. The infrastructure exists; wiring is the remaining work.

No DMA free

dma_dealloc is a no-op. Freed DMA pages are leaked. The BootInfoFrameAllocator has no reclamation path. Acceptable for MVP; a proper frame allocator with free would be needed for a production kernel.

Single device

The IRQ state (IRQ_PENDING) is a file-level static, supporting only one virtio-blk device. Multi-device support would require per-device state.

Heap size

The kernel heap is 100 KiB. DMA allocations come from the frame allocator (not the heap), but Vec<u8> read buffers and BlkReq/BlkResp structs live on the heap. Sustained I/O workloads should remain well within the limit.

VirtIO 9P Host Directory Sharing

Overview

The kernel includes a VirtIO 9P (9P2000.L) driver that shares a host directory directly into the guest via QEMU’s -fsdev mechanism. This provides a Docker-volume-like workflow: edit files on the host, they appear instantly in the guest — no disk image rebuild needed.

The driver uses the VirtIO9p device from the virtio-drivers crate (v0.13) and implements a minimal read-only 9P2000.L client on top.

Architecture

Host directory (./user)
        │
  QEMU virtio-9p-pci device
        │
        │  PciTransport (virtio-drivers)
        ▼
  VirtIO9p<KernelHal, PciTransport>   ← virtio device, raw request/response
        │
  spin::Mutex (synchronous access)
        │
  P9Client                             ← 9P2000.L protocol client
        │
  Plan9Vfs                             ← VFS adapter
        │
  devices::vfs mount table             ← /host and optionally /

Components

devices/src/virtio/p9_proto.rs — Wire Protocol

Minimal 9P2000.L message encoding/decoding. All messages use little-endian wire format with a 7-byte header: size[4] type[1] tag[2].

Message pairs implemented

Error responses use Rlerror (type 7) with a Linux errno code.

Key types

#![allow(unused)]
fn main() {
pub struct Qid { pub qid_type: u8, pub version: u32, pub path: u64 }
pub struct DirEntry9p { pub qid: Qid, pub offset: u64, pub dtype: u8, pub name: String }
pub struct Stat9p { pub mode: u32, pub size: u64, pub qid: Qid }
}

devices/src/virtio/p9.rs — P9Client

High-level client wrapping VirtIO9p. The device is accessed synchronously through a spin::Mutex — no actor pattern needed since 9P access happens from syscall context via osl::blocking::blocking().

#![allow(unused)]
fn main() {
pub struct P9Client {
    device: Mutex<VirtIO9p<KernelHal, PciTransport>>,
    msize:  u32,       // negotiated max message size (typically 8192)
    next_fid: Mutex<u32>,
}
}

Construction

P9Client::new(transport) performs the handshake:

1. Tversion — negotiates protocol version (“9P2000.L”) and max message size
2. Tattach — attaches root fid (fid 0) to the shared directory

Public methods

Each method walks from the root fid, allocating a temporary fid that is clunked after the operation completes. The readdir and read loops consume data in chunks of msize - 64 bytes.

list_dir filters out . and .. entries automatically.

devices/src/vfs/plan9_vfs.rs — VFS Adapter

Follows the ExfatVfs pattern. Wraps an Arc<P9Client> and maps:

• DirEntry9p → VfsDirEntry (dtype 4 or qid type 0x80 → is_dir)
• P9Error → VfsError

The P9Client methods are synchronous but the VFS interface is async. Since the virtio-9p device uses polling (no IRQ), blocking in an async context is acceptable for MVP.

QEMU Configuration

In scripts/run.sh:

-fsdev local,id=fsdev0,path=./user,security_model=none \
-device virtio-9p-pci,fsdev=fsdev0,mount_tag=hostfs

This shares the ./user directory (where userspace binaries are built) into the guest. security_model=none disables host permission mapping, which is appropriate since the guest is read-only.

Boot Sequence

run_kernel()
  1. PCI probe: find_devices(0x1AF4, 0x1049)   ← modern virtio-9p
                find_devices(0x1AF4, 0x1009)   ← legacy
  2. create_pci_transport(bus, dev, func)
  3. P9Client::new(transport)
       └─ Tversion + Tattach handshake
  4. Arc::new(client)
  5. vfs::mount("/host", Plan9(Plan9Vfs::new(Arc::clone(&client))))
  6. If no virtio-blk:
       vfs::mount("/", Plan9(Plan9Vfs::new(client)))

PCI Device IDs

Key Files

Limitations

Read-only

The 9P client only implements read operations (walk, lopen, read, readdir, getattr). Write, create, mkdir, remove, and rename are not supported.

No fid recycling

Fid numbers are allocated monotonically and never reused. With 32-bit fids this is unlikely to be a problem in practice, but a long-running system performing many file operations would eventually exhaust the fid space.

Directory entry sizes

list_dir reports size: 0 for all entries because readdir does not return file sizes. A per-entry getattr could be added but would increase the number of 9P round-trips.

Single device

Only one virtio-9p device is probed. Multiple shared directories would require iterating over all matching PCI devices and mounting each at a different path.

Synchronous I/O

All 9P operations block the calling scheduler thread. This is acceptable when called from syscall context via osl::blocking::blocking(), but direct use from async tasks would stall the executor.

exFAT Read-Only Filesystem

Overview

The kernel includes a read-only exFAT filesystem driver that sits on top of the virtio-blk block device. It auto-detects bare exFAT volumes, MBR-partitioned disks, and GPT-partitioned disks, then exposes simple directory-listing and file-read operations through the shell.

The driver is implemented entirely in devices/src/virtio/exfat.rs with no external dependencies.

Architecture

Shell (ls / cat / cd / pwd)
        │
        │  open_exfat / list_dir / read_file
        ▼
  ExfatVol  ──── async sector reads ────▶  BlkInbox
        │                                     │
  Partition detection                   VirtioBlkActor
  Boot sector parse                     (virtio-blk driver)
  FAT traversal
  Dir entry parse
  Path walk

All filesystem I/O is done one 512-byte sector at a time via the ask pattern on the virtio-blk actor’s mailbox (VirtioBlkMsg::Read).

Partition Auto-Detection

open_exfat reads sector 0 and applies the following decision tree:

sector0[3..11] == "EXFAT   "
  → bare exFAT (no partition table); volume starts at LBA 0

sector0[510..512] == [0x55, 0xAA]
  read sector 1
  sector1[0..8] == "EFI PART"
    → GPT: scan partition entries starting at the LBA stored in the header
      look for type GUID = EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
      (on-disk mixed-endian: A2 A0 D0 EB E5 B9 33 44 87 C0 68 B6 B7 26 99 C7)
      read StartingLBA of the matching entry, verify "EXFAT   " there
  else
    → MBR: scan partition table at sector0[446..510]
      look for entry with type byte 0x07
      read LBA start (bytes 8–11 LE u32), verify "EXFAT   " there

else
  → ExfatError::UnknownPartitionLayout

Type 0x07 is shared by exFAT and NTFS. The driver always verifies the OEM name at the candidate partition’s first sector before accepting it as exFAT.

On-Disk Layout

Boot Sector

FAT (File Allocation Table)

An array of u32 little-endian values. Entry N holds the next cluster in the chain for cluster N, or 0xFFFFFFFF for end-of-chain.

fat_lba          = volume_lba + FatOffset
sector_of_entry  = fat_lba + (N * 4) / 512
byte_in_sector   = (N * 4) % 512

Cluster Heap

cluster_lba(N) = cluster_heap_lba + (N − 2) * sectors_per_cluster

Cluster numbers start at 2; clusters 0 and 1 are reserved.

Directory Entry Sets

Each entry is 32 bytes. A file or directory is represented by a consecutive set of three or more entries:

Type 0x00 marks the end of directory; scanning stops immediately. Any type byte with bit 7 clear (< 0x80) is an unused or deleted entry and is skipped.

ExfatVol State

#![allow(unused)]
fn main() {
pub struct ExfatVol {
    lba_base:            u64,  // absolute LBA of the exFAT boot sector
    sectors_per_cluster: u64,
    fat_lba:             u64,  // absolute LBA of the FAT
    cluster_heap_lba:    u64,  // absolute LBA of the cluster heap
    root_cluster:        u32,
}
}

This is returned by open_exfat and passed to every subsequent call. The shell calls open_exfat fresh on each command (stateless).

Public API

#![allow(unused)]
fn main() {
/// Auto-detect layout and open the exFAT volume.
pub async fn open_exfat(inbox: &BlkInbox) -> Result<ExfatVol, ExfatError>;

/// List directory at `path` (e.g. "/" or "/docs").
pub async fn list_dir(vol: &ExfatVol, inbox: &BlkInbox, path: &str)
    -> Result<Vec<DirEntry>, ExfatError>;

/// Read a file into memory.  Capped at 16 KiB.
pub async fn read_file(vol: &ExfatVol, inbox: &BlkInbox, path: &str)
    -> Result<Vec<u8>, ExfatError>;
}

#![allow(unused)]
fn main() {
pub struct DirEntry {
    pub name:   String,
    pub is_dir: bool,
    pub size:   u64,
}

pub enum ExfatError {
    NoDevice, IoError, NotExfat, UnknownPartitionLayout,
    PathNotFound, NotAFile, NotADirectory, FileTooLarge,
}
}

BlkInbox is a type alias for the virtio-blk actor’s mailbox:

#![allow(unused)]
fn main() {
pub type BlkInbox = Arc<Mailbox<ActorMsg<VirtioBlkMsg, VirtioBlkInfo>>>;
}

Path Resolution

The shell maintains a current working directory (CWD) in Shell::cwd (spin::Mutex<String>, default "/").

resolve_path(cwd, path) in kernel/src/shell.rs handles relative and absolute paths, then normalize_path collapses . and .. components:

cwd = "/a/b"
resolve("../c")  →  normalize("/a/b/../c")  →  "/a/c"
resolve("/foo")  →  "/foo"
resolve("")      →  "/a/b"   (defaults to CWD)

Path component matching in the driver is case-insensitive ASCII (str::eq_ignore_ascii_case). Non-ASCII filename characters are replaced with ? in the decoded string.

Shell Commands

cd calls list_dir on the target path before updating the CWD, so invalid paths are rejected with an error rather than silently accepted.

Memory Budget

Peak heap usage during ls:

read_file caps output at 16 KiB. The kernel heap is 100 KiB; both operations are well within budget.

Limitations

Read-only

Write support is not implemented. VirtioBlkMsg::Write exists in the block driver but the exFAT layer has no write path.

Entry sets crossing cluster boundaries

scan_dir_cluster collects all sectors of a cluster into a flat buffer before parsing entries. An entry set whose 0x85 primary entry is in one cluster and whose secondary entries start in the next cluster will be silently skipped. This situation does not arise on normally-formatted volumes where directories start empty.

ASCII-only filenames

UTF-16LE code points above U+007F are replaced with ?. Files can still be opened by name if the shell command uses the same replacement — but in practice, test images should use ASCII filenames.

Fresh volume open per command

open_exfat reads the boot sector (and up to ~32 GPT entry sectors) on every shell command. A cached ExfatVol stored in the shell actor would reduce overhead, but is unnecessary given the current workload.

16 KiB file cap

read_file returns ExfatError::FileTooLarge for files exceeding 16 KiB. The limit exists to protect the 100 KiB heap; it can be raised if the heap is grown.

Key Files

Creating Test Images

GPT (macOS default)

hdiutil create -size 32m -fs ExFAT -volname TEST test-gpt.dmg
hdiutil attach test-gpt.dmg
cp hello.txt /Volumes/TEST/
mkdir /Volumes/TEST/subdir
cp nested.txt /Volumes/TEST/subdir/
hdiutil detach /Volumes/TEST
hdiutil convert test-gpt.dmg -format UDRO -o test-gpt-ro.dmg

MBR-partitioned

diskutil eraseDisk ExFAT TEST MBRFormat /dev/diskN

Bare exFAT (no partition table)

diskutil eraseVolume ExFAT TEST /dev/diskN

Running in QEMU

qemu-system-x86_64 ... \
  -drive file=test-gpt.img,format=raw,if=none,id=hd0 \
  -device virtio-blk-pci,drive=hd0

Then in the shell:

ostoo:/> ls
  [DIR]        subdir
  [FILE    13] hello.txt
ostoo:/> cat /hello.txt
Hello, kernel!
ostoo:/> cd subdir
ostoo:/subdir> ls
  [FILE    11] nested.txt
ostoo:/subdir> cat nested.txt
Hello again!
ostoo:/subdir> cd /
ostoo:/> pwd
/

Virtual Filesystem (VFS) Layer

Overview

The VFS layer provides a uniform path namespace over multiple filesystems. Before its introduction, the shell called the exFAT driver directly; adding a second filesystem would have required invasive shell changes. The VFS decouples path resolution and filesystem dispatch so that new drivers slot in without touching the shell.

Key properties:

• Enum dispatch — no heap-allocating Pin<Box<dyn Future>> trait objects.
• Mount table — filesystems are attached at arbitrary absolute paths.
• Lock safety — the mount-table lock is never held across an await point.
• No new Cargo dependencies — everything already present in the workspace.

Source layout

devices/src/
  vfs/
    mod.rs          — public API, mount table, path resolution
    exfat_vfs.rs    — ExfatVfs: wraps virtio-blk + exFAT driver
    plan9_vfs.rs    — Plan9Vfs: wraps virtio-9p P9Client
    proc_vfs/       — ProcVfs: synthetic kernel-info filesystem (mod.rs + generator submodules)

Public API (devices::vfs)

#![allow(unused)]
fn main() {
// Types
pub struct VfsDirEntry { pub name: String, pub is_dir: bool, pub size: u64 }

pub enum VfsError {
    IoError, NotFound, NotAFile, NotADirectory, FileTooLarge, NoFilesystem,
}

pub enum AnyVfs { Exfat(ExfatVfs), Plan9(Plan9Vfs), Proc(ProcVfs) }

// Functions
pub fn  mount(mountpoint: &str, fs: AnyVfs);
pub async fn list_dir(path: &str)  -> Result<Vec<VfsDirEntry>, VfsError>;
pub async fn read_file(path: &str) -> Result<Vec<u8>,          VfsError>;
pub fn  with_mounts<F: FnOnce(&[(String, Arc<AnyVfs>)])>(f: F);
}

All paths supplied to list_dir and read_file must be absolute (the shell’s resolve_path runs first and normalises . / ..).

Enum dispatch

Async methods on trait objects require Pin<Box<dyn Future>> — allocating and verbose in no_std. Instead, AnyVfs is a plain enum:

#![allow(unused)]
fn main() {
pub enum AnyVfs {
    Exfat(ExfatVfs),
    Plan9(Plan9Vfs),
    Proc(ProcVfs),
}

impl AnyVfs {
    pub async fn list_dir(&self, path: &str) -> Result<Vec<VfsDirEntry>, VfsError> {
        match self {
            AnyVfs::Exfat(fs) => fs.list_dir(path).await,
            AnyVfs::Plan9(fs) => fs.list_dir(path).await,
            AnyVfs::Proc(fs)  => fs.list_dir(path).await,
        }
    }
    // read_file, fs_type likewise
}
}

Adding a new filesystem = add one variant + three match arms (list_dir, read_file, fs_type).

Mount table

#![allow(unused)]
fn main() {
lazy_static! {
    static ref MOUNTS: spin::Mutex<Vec<(String, Arc<AnyVfs>)>> = ...;
}
}

Entries are kept sorted longest-mountpoint-first so resolution is a simple linear scan — the first match wins without any backtracking.

mount() replaces an existing entry at the same mountpoint, then re-sorts.

Arc<AnyVfs> is cloned out of the lock before any .await; the spinlock is never held across a suspension point.

Path resolution rules

#![allow(unused)]
fn main() {
fn resolve(path: &str) -> Option<(Arc<AnyVfs>, String)> {
    for (mp, fs) in MOUNTS.lock().iter() {
        if mp == "/"          { return Some((clone(fs), path.into())); }
        if path == mp         { return Some((clone(fs), "/".into())); }
        if path.starts_with(mp) && path[mp.len()..].starts_with('/') {
            return Some((clone(fs), path[mp.len()..].into()));
        }
    }
    None
}
}

ExfatVfs

ExfatVfs wraps a BlkInbox (the virtio-blk actor’s mailbox) and delegates to the existing devices::virtio::exfat functions. It calls open_exfat fresh on every request — identical to the pre-VFS shell behaviour.

ExfatVfs::list_dir / read_file
    └─ exfat::open_exfat  (detects bare/MBR/GPT layout)
    └─ exfat::list_dir / read_file

ExfatError → VfsError mapping:

Plan9Vfs

Plan9Vfs wraps an Arc<P9Client> and delegates to the 9P2000.L client. Unlike ExfatVfs (which goes through the actor/mailbox path), the P9 client performs synchronous virtio-9p device I/O directly under a spin::Mutex.

Plan9Vfs::list_dir / read_file
    └─ P9Client::list_dir / read_file
        └─ VirtIO9p::request (virtio-drivers)

P9Error → VfsError mapping:

The list_dir result sets is_dir from the dirent’s dtype field (4 = DT_DIR) or the qid type bit (0x80 = directory). The size field is 0 since readdir does not report file sizes — a follow-up stat per entry could be added later.

See docs/virtio-9p.md for the full 9P driver documentation.

ProcVfs

A synthetic filesystem with no block I/O. All content is computed on demand.

Data sources:

• executor::ready_count() / executor::wait_count() — task queue depths
• timer::ticks() / TICKS_PER_SECOND — seconds since boot
• driver::with_drivers() — registered driver names and states

Kernel initialisation (kernel/src/main.rs)

#![allow(unused)]
fn main() {
// Probe virtio-9p and create a shared P9Client.
let p9_client = probe_9p();  // returns Option<Arc<P9Client>>

// If 9p is available, always mount at /host.
if let Some(ref client) = p9_client {
    devices::vfs::mount("/host", AnyVfs::Plan9(Plan9Vfs::new(Arc::clone(client))));
}

// Always mount /proc — available without a block device.
devices::vfs::mount("/proc", AnyVfs::Proc(ProcVfs));

// Mount exFAT at / if virtio-blk was probed successfully.
let have_blk = if let Some(inbox) = registry::get::<..>("virtio-blk") {
    devices::vfs::mount("/", AnyVfs::Exfat(ExfatVfs::new(inbox)));
    true
} else { false };

// Fallback: mount 9p at / if no disk image is present.
if !have_blk {
    if let Some(client) = p9_client {
        devices::vfs::mount("/", AnyVfs::Plan9(Plan9Vfs::new(client)));
    }
}
}

This runs after both the virtio-blk and virtio-9p probe blocks and before task spawning. When both are present, exFAT owns / and 9p is at /host. When only 9p is present, it is mounted at both /host and / so that /shell auto-launch works without a disk image.

Shell integration (kernel/src/shell.rs)

The shell commands ls, cat, and cd now call the VFS API instead of the exFAT driver directly:

ls [path]   →  devices::vfs::list_dir(&path).await
cat <path>  →  devices::vfs::read_file(&path).await
cd [path]   →  devices::vfs::list_dir(&target).await  (directory check)

A new mount command manages the mount table at runtime:

mount                   — list all mounts
mount proc <mountpoint> — attach a ProcVfs instance
mount blk  <mountpoint> — attach an ExfatVfs instance (requires virtio-blk)

Example session

# Boot with 9p only (no disk image)
ostoo:/> mount
  /       9p
  /host   9p
  /proc   proc
ostoo:/> ls /
         shell
ostoo:/> ls /host
         shell
ostoo:/> cat /proc/uptime
42s

# Boot with both disk image and 9p
ostoo:/> mount
  /       exfat
  /host   9p
  /proc   proc
ostoo:/> ls /
  [DIR]        subdir
  [FILE    13]  hello.txt
ostoo:/> ls /host
         shell
ostoo:/> cat /host/shell | head
(binary ELF data)

Extending the VFS

To add a new filesystem type:

1. Create devices/src/vfs/<name>_vfs.rs implementing list_dir and read_file as plain async fn.
2. Add a variant to AnyVfs in mod.rs and two match arms in list_dir / read_file.
3. Re-export the new type from mod.rs.
4. Mount it from main.rs or the shell’s mount command.

No changes to the shell dispatch loop or path-resolution logic are required.

IPC Channels

Overview

Capability-based IPC channels for structured message passing between processes. A channel is a unidirectional message conduit with configurable buffer capacity. Channels come in pairs: a send end and a receive end, each exposed as a file descriptor (capability).

The buffer capacity, set at creation time, determines the communication model:

• capacity = 0 – Synchronous rendezvous. Sender blocks until a receiver calls recv. Direct message transfer with scheduler donate for minimal latency (matching seL4 endpoint characteristics).
• capacity > 0 – Asynchronous buffered. Sender enqueues and returns immediately. Blocks only when the buffer is full.

This gives applications full control: create a sync channel for tight RPC-style communication, or an async channel for decoupled producer-consumer patterns.

Message Format

struct ipc_message {
    uint64_t tag;       /* user-defined message type */
    uint64_t data[3];   /* 24 bytes of inline payload */
    int32_t  fds[4];    /* file descriptors for capability passing (-1 = unused) */
};
/* Total: 48 bytes */

The tag field is opaque to the kernel – applications use it to identify message types. The data array carries the payload (pointers, handles, small structs). The fds array carries file descriptors for capability passing (set unused slots to -1). For bulk data, use shared memory with a channel for signaling.

Syscalls

ipc_create (505)

long ipc_create(int fds[2], unsigned capacity, unsigned flags);

Creates a channel pair. Writes the send-end fd to fds[0] and the receive-end fd to fds[1].

Returns 0 on success, negative errno on failure.

ipc_send (506)

long ipc_send(int fd, const struct ipc_message *msg, unsigned flags);

Send a message through a send-end fd.

Blocking behavior:

• Sync (cap=0): blocks until a receiver calls recv, then transfers directly
• Async (cap>0): blocks only if the buffer is full

Returns 0 on success, -EPIPE if receive end is closed, -EAGAIN if non-blocking and would block.

ipc_recv (507)

long ipc_recv(int fd, struct ipc_message *msg, unsigned flags);

Receive a message from a receive-end fd.

Returns 0 on success, -EPIPE if send end is closed and no messages remain.

Examples

Sync channel (capacity=0)

int fds[2];
ipc_create(fds, 0, 0);         /* sync channel */
int send_fd = fds[0], recv_fd = fds[1];

/* In child (after clone+execve, with recv_fd inherited): */
struct ipc_message msg;
ipc_recv(recv_fd, &msg, 0);    /* blocks until parent sends */

/* In parent: */
struct ipc_message req = { .tag = 1, .data = {42, 0, 0}, .fds = {-1, -1, -1, -1} };
ipc_send(send_fd, &req, 0);    /* blocks until child recvs, then donates */

Async channel (capacity=4)

int fds[2];
ipc_create(fds, 4, 0);         /* buffered, 4 messages */

/* Producer can send 4 messages without blocking: */
for (int i = 0; i < 4; i++) {
    struct ipc_message m = { .tag = i };
    ipc_send(fds[0], &m, 0);
}

/* Consumer drains: */
struct ipc_message m;
while (ipc_recv(fds[1], &m, IPC_NONBLOCK) == 0) {
    /* process m */
}
/* returns -EAGAIN when empty */

fd-passing (capability transfer)

/* Create a pipe and an IPC channel */
int pipe_fds[2], ch_fds[2];
pipe(pipe_fds);
ipc_create(ch_fds, 4, 0);

/* Send the pipe write-end through the channel */
struct ipc_message msg = {
    .tag = 1,
    .data = { 0, 0, 0 },
    .fds = { pipe_fds[1], -1, -1, -1 },   /* transfer pipe write-end */
};
ipc_send(ch_fds[0], &msg, 0);

/* Receive — kernel allocates a new fd for the pipe write-end */
struct ipc_message recv_msg;
ipc_recv(ch_fds[1], &recv_msg, 0);
int new_write_fd = recv_msg.fds[0];   /* new fd number in receiver */

write(new_write_fd, "hello", 5);      /* writes to the same pipe */

Semantics: When ipc_send is called with non-(-1) values in the fds array, the kernel looks up each fd in the sender’s fd table, increments reference counts, and stores the kernel objects inside the channel. When ipc_recv delivers the message, the kernel allocates new fds in the receiver’s fd table and rewrites msg.fds with the new fd numbers.

Error handling: If any fd in msg.fds is invalid, the entire send fails with -EBADF. If the receiver’s fd table is full, recv fails with -EMFILE.

Cleanup: If a message with transferred fds is never received (e.g., the channel is destroyed with messages in the queue), the kernel closes the transferred fd objects automatically.

Kernel Implementation

Files

Sync rendezvous internals

When capacity=0, sender and receiver rendezvous directly:

1. If receiver is already blocked: sender copies message to pending_send, unblocks receiver, donates quantum via set_donate_target + yield_now
2. If no receiver: sender stores message in pending_send, records thread index, blocks via block_current_thread()
3. Receiver wakes, takes message from pending_send, unblocks sender

This uses the same block_current_thread / unblock / donate primitives as pipes and waitpid (see docs/scheduler-donate.md).

Async buffered internals

Messages are stored in a VecDeque<IpcMessage> bounded by capacity:

• Send: push to queue, wake blocked receiver if any
• Recv: pop from queue, wake blocked sender if queue was full
• Queue full: sender blocks until receiver drains
• Queue empty: receiver blocks until sender enqueues

Design Decisions

Unidirectional: Simpler and more composable than bidirectional. For RPC, use two channels (request + reply). For server fan-in, share the send-end fd via dup/fork.

Fixed-size messages: No heap allocation per message. 48 bytes fits common control-plane payloads plus 4 file descriptors for capability passing. Bulk data should use shared memory.

Capacity determines semantics: The application chooses sync vs async at creation time, not at each send/recv. This makes the channel’s behavior predictable and matches the Go channels model.

IPC_NONBLOCK flag: Adds flexibility for polling patterns and try-send/ try-recv without changing the channel’s fundamental semantics.

Channel as fd: Reuses the existing fd_table, close, dup2, CLOEXEC, and cleanup-on-exit infrastructure. No new kernel handle namespace.

Completion Port Integration

IPC channels can be multiplexed with other async I/O sources (IRQs, timers, file reads) via the completion port system.

OP_IPC_SEND (opcode 5)

Submit an IPC send as an async operation via io_submit. The message is read from user memory at submission time. If the channel can accept it immediately, a completion is posted right away. Otherwise the message is stored and the completion fires when a receiver drains space.

Submission fields:

Completion fields:

OP_IPC_RECV (opcode 6)

Submit an IPC receive as an async operation via io_submit. When a message arrives on the channel, a completion is posted to the port with the message copied to the user-provided buffer.

Submission fields:

Completion fields:

The message is copied to buf_addr by io_wait (same mechanism as OP_READ).

Semantics: Both operations are one-shot, like OP_IRQ_WAIT. Each submission handles exactly one message. Re-submit after each completion for continuous send/receive.

Example: event loop with IPC + timer

int port = io_create(0);
int fds[2];
ipc_create(fds, 4, 0);

struct ipc_message recv_buf;
struct io_submission subs[2] = {
    { .opcode = 6 /* OP_IPC_RECV */, .fd = fds[1],
      .buf_addr = (uint64_t)&recv_buf, .user_data = 1 },
    { .opcode = 1 /* OP_TIMEOUT */, .timeout_ns = 1000000000, .user_data = 2 },
};
io_submit(port, subs, 2);

struct io_completion comp;
io_wait(port, &comp, 1, 1, 0);
if (comp.user_data == 1) {
    /* IPC message received in recv_buf */
} else {
    /* timer fired */
}

Kernel internals

When io_submit processes OP_IPC_RECV, it calls arm_recv():

1. If a message is already in the queue, posts a completion immediately
2. Otherwise, registers the port on the channel (pending_port field)
3. When a future ipc_send deposits a message, try_send detects the armed port and returns SendAction::PostToPort — the caller serializes the message and posts it to the port after releasing the channel lock

When io_submit processes OP_IPC_SEND, it calls arm_send():

1. If the channel can accept the message (queue not full, or receiver waiting), delivers it and posts a success completion immediately
2. Otherwise, stores the port + message in pending_send_port
3. When a future ipc_recv drains space, try_recv detects the armed send port and returns RecvAction::MessageAndNotifySendPort — the caller posts a success completion to the send port

Lock ordering: channel lock is always acquired before port lock (never reversed), preventing deadlocks.

Future Extensions

• ipc_call(fd, send_msg, recv_msg) – atomic send+recv for RPC
• Bidirectional channels – two queues in one object
• fd-passing in messages – implemented: fds[4] in IpcMessage, kernel transfers fd objects between processes
• Notification objects – seL4-style bitmask signaling

Completion Port Design

Overview

This document describes a unified completion-based async I/O primitive (CompletionPort) for ostoo. The design supports both io_uring-style and Windows IOCP-style patterns through a single kernel object, accessed as an ordinary file descriptor.

The CompletionPort is motivated by the microkernel migration path (microkernel-design.md, Phases B-E) where userspace drivers need to wait on multiple event sources — IRQs, shared-memory ring wakeups, timers — through a single blocking wait point, without polling or managing multiple threads.

See also: mmap-design.md for the shared memory primitives that enable the zero-syscall ring optimisation (Phase 5 of this design).

Motivation

The Problem

A userspace NIC driver in the microkernel architecture must simultaneously wait for:

1. IRQ events — the device raised an interrupt
2. Ring wakeups — the TCP/IP server posted new transmit descriptors
3. Timers — a retransmit or watchdog timer expired

With the current kernel, each of these is a separate blocking read() on a separate fd. A driver would need one thread per event source, or a poll()/ select() readiness multiplexer — neither of which exists yet.

Why Completion-Based

A completion-based model inverts the usual readiness pattern:

• Readiness (epoll/poll/select): “tell me when fd X is ready, then I’ll do the I/O myself.” Two syscalls per operation (wait + read/write).
• Completion (io_uring/IOCP): “do this I/O for me and tell me when it’s done.” One syscall to submit, one to reap — or zero with shared-memory rings.

Completion-based I/O is a better fit for ostoo because:

• Simpler driver loops. Submit work, wait for completions. No edge- triggered vs level-triggered subtlety.
• Naturally batched. Multiple operations submitted and reaped per syscall.
• Unifies heterogeneous events. IRQs, timers, and file I/O all produce the same IoCompletion struct.
• Shared-memory fast path. The submission/completion queues can be mapped into userspace for zero-syscall operation under load (Phase 5).
• Matches the microkernel data plane. Drivers post work and reap completions — the same pattern as managing hardware descriptor rings.

How Other Systems Do It

Linux io_uring

Introduced in 5.1. Submission Queue (SQ) and Completion Queue (CQ) are shared-memory ring buffers mapped into userspace. The kernel polls the SQ for new entries; completions appear in the CQ. io_uring_enter() is the single syscall (submit + wait).

• Supports 60+ operation types (read, write, accept, timeout, etc.)
• SQEs carry a user_data field returned verbatim in CQEs for demux
• IORING_SETUP_SQPOLL mode: kernel thread polls the SQ — truly zero- syscall submission under load
• Fixed-file and fixed-buffer registration to avoid per-op fd/buffer lookup

Windows IOCP (I/O Completion Ports)

The original completion-based API (NT 3.5, 1994). A completion port is a kernel object that aggregates completions from multiple file handles.

• CreateIoCompletionPort() creates the port and associates handles
• Async operations (ReadFile, WriteFile with OVERLAPPED) post completions to the associated port
• GetQueuedCompletionStatus() dequeues one completion (blocking)
• PostQueuedCompletionStatus() manually posts a completion (for app-level signaling)
• The kernel limits concurrent threads to the port’s concurrency value

Fuchsia zx_port

Zircon ports are the unified event aggregation primitive:

• zx_port_create() creates a port
• zx_object_wait_async() registers interest in an object’s signals (channels, interrupts, timers, processes) — when the signal fires, a packet is queued to the port
• zx_port_wait() dequeues a packet (blocking with optional timeout)
• zx_port_queue() manually enqueues a user packet
• Packets carry a key field for demux (equivalent to user_data)

seL4 Notifications

seL4 uses a minimal signaling primitive:

• A notification is a word-sized bitmask of binary semaphores
• seL4_Signal() OR-sets bits; seL4_Wait() atomically reads and clears
• Multiple event sources (IRQs, IPC completions) signal different bits in the same notification
• One seL4_Wait() multiplexes all sources — the returned word tells which bits fired
• Limitation: carries no payload beyond the bitmask. Data transfer requires a separate shared-memory protocol

Comparison

Core Abstraction

A CompletionPort is a kernel object consisting of a FIFO completion queue and a waiter slot. It is accessed through a file descriptor, like any other ostoo resource.

                   ┌─────────────────────────────┐
                   │       CompletionPort         │
                   │                              │
  io_submit ──────▶│  ┌─────────────────────────┐ │
                   │  │   Completion Queue       │ │
  IRQ ISR ────────▶│  │  ┌────┬────┬────┬───┐   │ │
                   │  │  │ C0 │ C1 │ C2 │...│   │ │──────▶ io_wait
  Timer expire ───▶│  │  └────┴────┴────┴───┘   │ │        (blocks until
                   │  └─────────────────────────┘ │         non-empty)
  Ring wakeup ────▶│                              │
                   │  waiter: Option<thread_idx>  │
                   └─────────────────────────────┘

Key properties:

• Single consumer. Only one thread may call io_wait on a port at a time. This avoids thundering-herd complexity and matches the single- threaded driver loop model.
• Multiple producers. Any context — syscall path, ISR, timer callback — can post a completion to the queue.
• User_data demux. Every submission carries a u64 user_data field that is returned verbatim in the completion, allowing the caller to identify which operation completed without inspecting the payload.
• Port as fd. The port lives in the process’s fd_table and can be closed, passed across execve (unless FD_CLOEXEC), or used with dup2.

Syscall Interface

Three syscalls using custom numbers in the 500+ range:

io_create (501)

Creates a new CompletionPort and returns its file descriptor.

• flags: reserved, must be 0. Future: IO_CLOEXEC.
• Returns: fd on success, negative errno on failure.

io_submit (502)

Submits one or more I/O operations to the port.

• port_fd: fd returned by io_create.
• entries: pointer to an array of IoSubmission structs in user memory.
• count: number of entries to submit (0 < count ≤ 64).
• Returns: number of entries successfully submitted, or negative errno.

Submissions that reference invalid fds or unsupported operations fail individually — the return value indicates how many of the leading entries were accepted.

io_wait (503)

Waits for completions and copies them to user memory.

• port_fd: fd returned by io_create.
• completions: pointer to an array of IoCompletion structs in user memory.
• max: maximum number of completions to return.
• min: minimum number to wait for before returning (0 = non-blocking poll).
• timeout_ns: maximum wait time in nanoseconds. 0 = no timeout (wait indefinitely for min completions). With min=0, returns immediately.
• Returns: number of completions written, or negative errno.

IoSubmission struct

#![allow(unused)]
fn main() {
#[repr(C)]
pub struct IoSubmission {
    pub user_data: u64,   // returned in completion, opaque to kernel
    pub opcode: u32,      // OP_NOP, OP_READ, etc.
    pub flags: u32,       // per-op flags, reserved
    pub fd: i32,          // target fd (for OP_READ, OP_WRITE)
    pub _pad: i32,
    pub buf_addr: u64,    // user buffer pointer
    pub buf_len: u32,     // buffer length
    pub offset: u32,      // file offset (low 32 bits, sufficient initially)
    pub timeout_ns: u64,  // for OP_TIMEOUT
}
}

Total size: 48 bytes.

IoCompletion struct

#![allow(unused)]
fn main() {
#[repr(C)]
pub struct IoCompletion {
    pub user_data: u64,   // copied from submission
    pub result: i64,      // bytes transferred, or negative errno
    pub flags: u32,       // completion flags (reserved)
    pub opcode: u32,      // echoed from submission
}
}

Total size: 24 bytes.

Operations

OP_NOP (0)

Immediately posts a completion with result = 0. No side effects. Used for round-trip latency testing and as a wake-up mechanism (submit a NOP from another thread to unblock io_wait).

OP_TIMEOUT (1)

Registers a one-shot timer. Completes after timeout_ns nanoseconds with result = 0, or result = -ETIME if cancelled (future).

Implementation: uses the existing libkernel::task::timer (Delay/Sleep) infrastructure. The submission spawns an async delay task that posts the completion when the timer fires.

OP_READ (2)

Reads up to buf_len bytes from fd at offset into buf_addr.

• result = number of bytes read, or negative errno.
• For console/pipe fds (no meaningful offset), offset is ignored.

Implementation: see “Sync fallback worker” below.

OP_WRITE (3)

Writes up to buf_len bytes from buf_addr to fd at offset.

• result = number of bytes written, or negative errno.

Implementation: same sync fallback pattern as OP_READ.

OP_IRQ_WAIT (4)

Waits for a hardware interrupt on an IRQ fd (from microkernel-design.md, Phase B).

• fd must be an IRQ fd (IrqHandle).
• result = interrupt count since last wait, or negative errno.

Implementation: the IRQ fd’s ISR-safe notification calls port.post() when the interrupt fires. No worker thread needed — the ISR posts directly.

OP_IPC_SEND (5)

Sends a message through an IPC channel send-end fd as an async operation.

• fd must be a channel send-end fd.
• buf_addr points to a user-space struct ipc_message (48 bytes).
• result = 0 on success, -EPIPE if receive end closed.

The message (including any fd-passing entries in fds[4]) is read from user memory at submission time. If the channel can accept the message immediately, a completion is posted right away. Otherwise the message is stored and the completion fires when a receiver drains space.

See ipc-channels.md for full details.

OP_IPC_RECV (6)

Receives a message from an IPC channel receive-end fd as an async operation.

• fd must be a channel receive-end fd.
• buf_addr points to a user-space struct ipc_message buffer (48 bytes).
• result = 0 on success, -EPIPE if send end closed and no messages remain.

When a message arrives on the channel, a completion is posted to the port. The message (including any transferred fds, allocated in the receiver’s fd table) is copied to buf_addr during io_wait.

See ipc-channels.md for full details.

OP_RING_WAIT (7) — Implemented

Waits for a notification fd to be signaled.

• fd must be a notification fd (from notify_create, syscall 509).
• result = 0 on wakeup, or negative errno.

Implementation: the consumer submits OP_RING_WAIT via io_submit. The kernel stores the port + user_data on the NotifyInner object. When the producer calls notify(fd) (syscall 510), the kernel posts a completion to the port. No worker thread needed — the syscall posts directly.

Edge-triggered, one-shot: one notify() → one completion. Consumer must re-submit OP_RING_WAIT to rearm. If notify() is called before OP_RING_WAIT is armed, the notification is buffered (coalesced).

The notification fd is a general-purpose signaling primitive, not tied to any specific ring buffer format. The kernel does not inspect ring buffer contents — it simply provides the signal/wait mechanism.

Kernel Implementation Sketch

CompletionPort struct

#![allow(unused)]
fn main() {
use alloc::collections::VecDeque;

pub struct CompletionPort {
    queue: VecDeque<IoCompletion>,
    waiter: Option<usize>,       // thread index blocked in io_wait
    max_queued: usize,           // backpressure limit (default 256)
}
}

The CompletionPort is wrapped in a Mutex and stored inside a CompletionPortHandle that implements FileHandle.

CompletionPortHandle

#![allow(unused)]
fn main() {
pub struct CompletionPortHandle {
    port: Arc<Mutex<CompletionPort>>,
}
}

Implements FileHandle:

• read() → returns Err(FileError::BadFd) (use io_wait instead)
• write() → returns Err(FileError::BadFd) (use io_submit instead)
• close() → drop the Arc. Pending operations are cancelled (completions with -ECANCELED are discarded).
• kind() → a new FileKind::CompletionPort variant

ISR-safe post()

The post() method must be callable from interrupt context (e.g., an IRQ handler posting OP_IRQ_WAIT completions).

#![allow(unused)]
fn main() {
impl CompletionPort {
    /// Post a completion.  Safe to call from ISR context.
    pub fn post(&mut self, completion: IoCompletion) {
        if self.queue.len() < self.max_queued {
            self.queue.push_back(completion);
        }
        // Wake the blocked waiter, if any
        if let Some(thread_idx) = self.waiter.take() {
            scheduler::unblock(thread_idx);
        }
    }
}
}

The CompletionPort is wrapped in an IrqMutex which disables interrupts while held, making post() safe to call from ISR context.

io_wait blocking pattern

sys_io_wait(port_fd, completions_ptr, max, min, timeout_ns):
    port = lookup_fd(port_fd) as CompletionPortHandle
    loop:
        lock port
        n = drain up to max completions from queue
        if n >= min:
            copy n completions to user memory
            return n
        register current thread as waiter
        unlock port
        block_current_thread()       // scheduler marks Blocked, yields
        // ... woken by post() or timeout ...
    if timeout expired:
        return completions drained so far (may be 0)

This reuses the existing scheduler::block_current_thread() / scheduler::unblock() pattern from the pipe and waitpid implementations.

Sync fallback worker for OP_READ / OP_WRITE

Existing FileHandle implementations (VfsHandle, ConsoleHandle, PipeReader) are synchronous and blocking. To integrate them with the CompletionPort without rewriting every handle:

1. io_submit for OP_READ/OP_WRITE spawns an async task (via the existing executor).
2. The task calls osl::blocking::blocking() which blocks a scheduler thread on the synchronous FileHandle::read() or FileHandle::write().
3. When the blocking call returns, the task posts a completion to the port.

This means each in-flight OP_READ/OP_WRITE consumes one scheduler thread while blocked. Acceptable for the initial implementation; a true async FileHandle path can be added later.

io_submit(OP_READ, fd, buf, len):
    spawn async {
        let result = blocking(|| {
            file_handle.read(buf, len)
        });
        port.lock().post(IoCompletion {
            user_data,
            result: result as i64,
            opcode: OP_READ,
            flags: 0,
        });
    }

Integration with Existing Infrastructure

FileHandle trait

No changes to the FileHandle trait in Phase 1. The sync fallback worker bridges existing handles.

In a future phase, an optional submit_async() method could be added to FileHandle for handles that can natively post completions (e.g., a future async virtio-blk driver):

#![allow(unused)]
fn main() {
pub trait FileHandle: Send + Sync {
    // ... existing methods ...

    /// Submit an async operation.  Default: not supported (use sync fallback).
    fn submit_async(&self, _op: &IoSubmission, _port: &Arc<Mutex<CompletionPort>>)
        -> Result<(), FileError>
    {
        Err(FileError::NotSupported)
    }
}
}

Executor and timer reuse

• Executor: the existing async task executor spawns fallback worker tasks and timeout tasks. No changes needed.
• Timer: OP_TIMEOUT uses the existing libkernel::task::timer::Delay (which builds on the LAPIC timer tick). No new timer infrastructure.

fd_table

The CompletionPort is stored in the process fd_table as a CompletionPortHandle. This means:

• close(port_fd) cleans up the port.
• dup2 works (two fds alias the same port via Arc).
• FD_CLOEXEC / close_cloexec_fds() works for execve.
• No new kernel data structures outside the existing fd model.

Syscall dispatch wiring

Add to osl/src/syscalls/mod.rs:

#![allow(unused)]
fn main() {
501 => sys_io_create(a1 as u32),
502 => sys_io_submit(a1 as i32, a2 as *const IoSubmission, a3 as u32),
503 => sys_io_wait(a1 as i32, a2 as *mut IoCompletion, a3 as u32, a4 as u32, a5 as u64),
}

The IoSubmission and IoCompletion structs live in osl/src/io_port.rs (new file). The CompletionPort and CompletionPortHandle implementations live in libkernel/src/file.rs alongside the existing handle types.

Integration with Microkernel Primitives

The CompletionPort replaces the need for two separate primitives described in microkernel-design.md:

• IRQ fd (Phase B) — instead of a standalone IrqHandle where read() blocks, the IRQ fd posts completions to a port via OP_IRQ_WAIT. The driver submits an OP_IRQ_WAIT and reaps it alongside other completions.

• Notification objects (seL4-style) — unnecessary. A port with manual post() (exposed as a future io_post syscall or via OP_NOP with user_data tagging) serves the same role.

NIC driver example loop

int port = io_create(0);
int irq_fd = open("/dev/irq/11", O_RDONLY);
int ring_fd = open("/dev/shm/txring", O_RDWR);

// Submit initial waits
IoSubmission subs[2] = {
    { .user_data = TAG_IRQ,  .opcode = OP_IRQ_WAIT,  .fd = irq_fd  },
    { .user_data = TAG_RING, .opcode = OP_RING_WAIT, .fd = ring_fd },
};
io_submit(port, subs, 2);

for (;;) {
    IoCompletion comp[8];
    int n = io_wait(port, comp, 8, /*min=*/1, /*timeout=*/0);

    for (int i = 0; i < n; i++) {
        switch (comp[i].user_data) {
        case TAG_IRQ:
            handle_interrupt();
            // Resubmit IRQ wait
            io_submit(port, &(IoSubmission){
                .user_data = TAG_IRQ, .opcode = OP_IRQ_WAIT, .fd = irq_fd
            }, 1);
            break;

        case TAG_RING:
            drain_tx_ring();
            // Resubmit ring wait
            io_submit(port, &(IoSubmission){
                .user_data = TAG_RING, .opcode = OP_RING_WAIT, .fd = ring_fd
            }, 1);
            break;
        }
    }
}

This single-threaded loop handles both IRQs and ring wakeups through one blocking wait point — exactly the pattern needed for microkernel drivers.

Shared-Memory Ring Optimisation (Phase 5 — Implemented)

Under high throughput, even one syscall per batch can become a bottleneck. The shared-memory ring optimisation maps the submission and completion queues into userspace as shared-memory ring buffers, eliminating syscalls on the hot path for reading completions.

Syscalls

io_setup_rings (511)

io_setup_rings(port_fd, params: *mut IoRingParams) → 0 or -errno

Allocates SQ and CQ ring pages and returns shmem fds that the process mmaps with MAP_SHARED:

struct io_ring_params params = { .sq_entries = 64, .cq_entries = 128 };
io_setup_rings(port, &params);
void *sq = mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_SHARED, params.sq_fd, 0);
void *cq = mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_SHARED, params.cq_fd, 0);

io_ring_enter (512)

io_ring_enter(port_fd, to_submit, min_complete, flags) → i64

Processes up to to_submit SQEs from the shared SQ ring, flushes deferred completions, and optionally blocks until min_complete CQEs are available in the CQ ring.

Ring layout

Single 4 KiB page per ring:

Offset 0:  RingHeader (16 bytes)
  AtomicU32 head  — consumer advances (SQ: kernel, CQ: user)
  AtomicU32 tail  — producer advances (SQ: user, CQ: kernel)
  u32 mask        — capacity - 1
  u32 flags       — reserved (0)

Offset 64: entries[] (cache-line aligned)
  SQ: IoSubmission[capacity]  — 48 bytes each, max 64
  CQ: IoCompletion[capacity]  — 24 bytes each, max 128

Head and tail use atomic load/store with acquire/release ordering.

Dual-mode post()

When rings are active, CompletionPort::post() routes completions:

• Simple (no read_buf, no transfer_fds): CQE written directly to the shared CQ ring via IoRing::post_cqe(). Fast path for OP_NOP, OP_TIMEOUT, OP_WRITE, OP_IRQ_WAIT, OP_IPC_SEND, OP_RING_WAIT.
• Deferred (read_buf or transfer_fds present): pushed to the kernel VecDeque. io_ring_enter flushes these in syscall context where page tables are correct for data copy and fd installation.

Backward compatibility

• io_submit works in ring mode (completions go to CQ ring)
• io_wait returns -EINVAL in ring mode (use io_ring_enter)
• Ports without rings work exactly as before

Phased Implementation

Phase 1: Core + OP_NOP + OP_TIMEOUT

Goal: Establish the CompletionPort kernel object, syscall interface, and basic operations.

Phase 2: OP_READ + OP_WRITE with Sync Fallback

Goal: Bridge existing FileHandle implementations into the completion model.

Phase 3: OP_IRQ_WAIT — Implemented

Goal: Hardware interrupt delivery through the completion port.

Phase 3b: OP_IPC_SEND + OP_IPC_RECV — Implemented

Goal: Multiplex IPC channel operations with other async I/O sources.

Phase 4: OP_RING_WAIT — Implemented

Goal: Inter-process signaling through the completion port via notification fds.

Phase 5: Shared-Memory SQ/CQ Rings — Implemented

Goal: Zero-syscall submission and completion for high-throughput paths.

Dependency Graph

                     ┌────────────────────────┐
                     │  Phase 1               │
                     │  Core + NOP + TIMEOUT   │
                     │  (no external deps)     │
                     └──┬──────────┬───────┬──┘
                        │          │       │
               ┌────────▼──┐   ┌──▼────┐  │
               │  Phase 2   │  │       │  │
               │  READ/WRITE│  │       │  │
               │  sync fbk  │  │       │  │
               └────────────┘  │       │  │
                               │       │  │
          ┌────────────────────┘       │  │
          │                            │  │
  ┌───────▼────────┐  ┌───────────┐   │  │
  │  Phase 3  ✓    │  │ Phase 3b ✓│   │  │
  │  OP_IRQ_WAIT   │  │ OP_IPC_*  │   │  │
  │                │  │           │   │  │
  │  requires:     │  │ requires: │   │  │
  │  IO APIC       │  │ IPC chans │   │  │
  └────────────────┘  └───────────┘   │  │
                                      │  │
          ┌────────────────────┐      │  │
          │  Phase 4  ✓        │      │  │
          │  OP_RING_WAIT      │      │  │
          │  (notify fds)      │      │  │
          └────────────────────┘      │  │
                                      │  │
                    ┌─────────────────▼──▼───────────────┐
                    │  Phase 5  ✓                        │
                    │  Shared-memory SQ/CQ rings         │
                    │                                    │
                    │  requires:                         │
                    │  mmap Phase 5 (MAP_SHARED)  ✓      │
                    └────────────────────────────────────┘

All phases are complete.

Key Design Decisions

Syscall-first, not ring-first

Phase 1 uses traditional syscalls (io_submit/io_wait). Shared-memory rings are deferred to Phase 5. This avoids coupling the initial implementation to MAP_SHARED (which is not yet implemented) and keeps the kernel-side logic simple.

Port as fd

The CompletionPort is an fd in the process’s fd_table, not a special kernel handle type. This reuses existing infrastructure (close, dup2, CLOEXEC, fd_table cleanup on exit) and avoids inventing a parallel handle namespace.

Eager posting

Completions are pushed to the port’s queue immediately when the operation finishes (or the ISR fires). There is no lazy/deferred completion model. This is simpler and matches the existing block/unblock scheduling model.

Single-threaded wait

Only one thread may block in io_wait per port. This is a deliberate constraint matching the single-threaded driver loop model. Multi-threaded consumers can use multiple ports. This avoids thundering-herd wake-up logic and lock contention on the completion queue.

user_data for demux

Every submission carries a u64 user_data returned verbatim in the completion. The kernel never inspects this field. The caller uses it to identify which logical operation completed (e.g., TAG_IRQ, TAG_RING, a pointer to a request struct). This is the same pattern used by io_uring, IOCP, and Fuchsia ports.

Custom syscall numbers (501-503)

The 500+ range is reserved for ostoo-specific syscalls. These are not Linux syscall numbers. If Linux compatibility is needed later, a shim layer can map Linux’s io_uring_setup/io_uring_enter numbers to the ostoo equivalents.

Kernel-buffered queue

The completion queue lives in kernel memory (VecDeque<IoCompletion>), not shared memory. io_wait copies completions to user buffers. Simple, correct, and sufficient until Phase 5 adds the zero-copy shared-memory path.

Sync fallback for existing FileHandles

Rather than rewriting ConsoleHandle, PipeReader, VfsHandle, etc. to be async-aware, OP_READ/OP_WRITE spawn a blocking worker that calls the existing synchronous FileHandle::read()/FileHandle::write() and posts the completion when done. This trades a scheduler thread per in-flight op for zero changes to existing handle implementations.

Timer via Delay

OP_TIMEOUT reuses the existing libkernel::task::timer::Delay rather than introducing a new timer subsystem. The LAPIC timer already provides 10ms ticks; Delay builds on this.

ISR-safe posting

CompletionPort::post() must work from interrupt context. The IrqMutex around the port disables interrupts while held. The scheduler::unblock() call is already ISR-safe (it just pushes to the ready queue).

No cancellation in Phase 1

Submitted operations cannot be cancelled. This avoids the complexity of cancellation tokens, in-progress state tracking, and partial-completion semantics. Cancellation support can be added later as an io_cancel syscall (504) once the basic model is proven.

Completion-oriented, not readiness-oriented

The port reports “operation X is done” (completion), not “fd Y is readable” (readiness). This is a deliberate choice:

• Completion avoids the double-syscall problem (wait for ready, then do I/O).
• Completion naturally supports heterogeneous event sources (timers, IRQs) that don’t have a “ready” state.
• Readiness can be emulated on top of completion (submit a zero-length OP_READ as a readiness probe) but not vice versa.

Blocking Protocol

This document describes the blocking/wakeup protocol used throughout the kernel, the lost-wakeup race it currently suffers from, and a proposed fix based on an idle thread and a WaitCondition primitive.

Formal PlusCal/TLA+ models of the protocol live in specs/. See specs/PLUSCAL.md for authoring instructions and specs/README.md for per-spec details.

Current protocol (buggy)

Every blocking site in the kernel follows this pattern:

#![allow(unused)]
fn main() {
{
    let mut guard = shared_state.lock();   // 1. acquire lock
    guard.waiter = Some(thread_idx);       // 2. register waiter
}                                          // 3. release lock
scheduler::block_current_thread();         // 4. mark Blocked + spin
}

The waker (a producer, timer, or signal) does:

#![allow(unused)]
fn main() {
{
    let mut guard = shared_state.lock();
    if let Some(t) = guard.waiter.take() { // clear waiter slot
        scheduler::unblock(t);             // wake up the blocked thread
    }
}
}

And unblock() is conditional:

#![allow(unused)]
fn main() {
pub fn unblock(thread_idx: usize) {
    let mut sched = SCHEDULER.lock();
    if let Some(t) = sched.threads.get_mut(thread_idx) {
        if t.state == ThreadState::Blocked {   // <-- only acts if Blocked
            t.state = ThreadState::Ready;
            sched.ready_queue.push_back(thread_idx);
        }
    }
}
}

The race

A waker can execute between steps 3 (unlock) and 4 (mark Blocked):

1. Waiter: acquires lock, sets waiter = Some(self), releases lock. Thread state is still Running.
2. Waker: acquires lock, calls waiter.take(), calls unblock(waiter). unblock checks state == Blocked — it’s Running — no-op. Waiter slot is now None.
3. Waiter: calls block_current_thread(), sets state to Blocked, spins forever. No future waker will call unblock because the waiter slot was already consumed. Deadlock.

This race is confirmed by the PlusCal model in specs/completion_port/completion_port.tla (TLC finds a deadlock trace) and by code inspection of scheduler.rs lines 640-676.

Affected sites

The race affects every blocking site, not just the completion port:

The IPC channel sites (sys_ipc_send, sys_ipc_recv) use the split mark_blocked() / yield_now() pair. The mark_blocked is called inside ChannelInner::try_send/try_recv (under the IrqMutex), and the caller does yield_now() after the lock drops via the SendAction/RecvAction enum. These are already race-free; WaitCondition doesn’t fit the action-enum pattern without a larger refactor.

The sys_io_ring_enter variant previously had an additional bug: check and set_waiter were under separate lock acquisitions, so a completion could arrive between the check and the registration. WaitCondition fixes this by construction.

Why Blocked threads spin today

Both preempt_tick and yield_tick handle an empty ready queue by returning current_rsp — i.e. they keep running the current thread even if it’s Blocked. This forces block_current_thread() to include a HLT spin loop: the Blocked thread keeps running on the CPU, calling enable_and_hlt() in a loop, waiting for the next timer interrupt to check if unblock() has changed its state. This wastes up to one full quantum (10ms) per blocking event and prevents the CPU from doing useful work while the thread is Blocked.

Proposed fix

The fix has three parts: an idle thread that eliminates the need for blocked threads to spin, a split of block_current_thread that fixes the race, and a WaitCondition wrapper that makes the correct pattern easy and the buggy pattern impossible.

Step 1: Add an idle thread

Create a per-CPU idle thread that the scheduler falls back to when the ready queue is empty. The idle thread does nothing but HLT in a loop, yielding the CPU until the next interrupt:

#![allow(unused)]
fn main() {
fn idle_thread() -> ! {
    loop {
        x86_64::instructions::interrupts::enable_and_hlt();
    }
}
}

The idle thread is created during scheduler init and stored in Scheduler:

#![allow(unused)]
fn main() {
struct Scheduler {
    // ...
    idle_thread_idx: usize,  // always present, never on the ready queue
}
}

Then preempt_tick and yield_tick switch to the idle thread instead of staying on a Blocked/Dead thread:

#![allow(unused)]
fn main() {
let next_idx = match sched.ready_queue.pop_front() {
    Some(idx) => idx,
    None => sched.idle_thread_idx,  // was: return current_rsp
};
}

The idle thread is never pushed onto the ready queue. The scheduler only runs it as a fallback when nothing else is Ready. The first unblock() call pushes a real thread onto the ready queue, and the next timer tick preempts idle and switches to it.

With this change, a Blocked thread no longer needs to spin — the scheduler context-switches away from it immediately and never schedules it again until unblock() makes it Ready.

Step 2: Split block_current_thread into mark + yield

#![allow(unused)]
fn main() {
/// Mark the current thread Blocked and yield to the scheduler.
///
/// Safe to call while holding any lock (acquires SCHEDULER briefly).
/// The scheduler will context-switch away and never schedule this thread
/// again until unblock() is called. Execution resumes at the instruction
/// after this call.
// [spec: completion_port/completion_port.tla CheckAndAct — "thread_state := blocked"
//        + WaitUnblocked — "await thread_state = running"]
pub fn mark_blocked_and_yield() {
    x86_64::instructions::interrupts::without_interrupts(|| {
        let mut sched = SCHEDULER.lock();
        let idx = sched.current_idx;
        sched.threads[idx].state = ThreadState::Blocked;
    });
    yield_now();  // context-switch away; resume here after unblock + reschedule
}
}

There is no spin loop. yield_now() triggers int 0x50, which enters yield_tick. The scheduler sees the thread is Blocked, does not re-queue it, and switches to the next ready thread (or idle). When unblock() is called later, the thread is pushed onto the ready queue with state Ready. The scheduler eventually picks it and context-switches back, resuming execution right after the yield_now() call.

A separate mark_blocked() (without yield) is still useful for callers that need to mark Blocked under a lock and yield after dropping it:

#![allow(unused)]
fn main() {
/// Mark the current thread Blocked. Does NOT yield.
/// Caller must call yield_now() after releasing their lock.
pub fn mark_blocked() {
    x86_64::instructions::interrupts::without_interrupts(|| {
        let mut sched = SCHEDULER.lock();
        let idx = sched.current_idx;
        sched.threads[idx].state = ThreadState::Blocked;
    });
}
}

Step 3: Migrate call sites

Each site becomes:

#![allow(unused)]
fn main() {
{
    let mut guard = shared_state.lock();   // 1. acquire lock
    guard.waiter = Some(thread_idx);       // 2. register waiter
    scheduler::mark_blocked();             // 3. mark Blocked UNDER LOCK
}                                          // 4. release lock
scheduler::yield_now();                    // 5. context-switch away
// execution resumes here after unblock + reschedule
}

No loop, no spin, no HLT. The thread is off the CPU until explicitly woken.

Step 4: Introduce WaitCondition to enforce the pattern (DONE)

Implemented in libkernel/src/wait_condition.rs. Seven sites now use WaitCondition::wait_while(): sys_io_wait, sys_io_ring_enter, PipeReader::read, read_input (console), sys_wait4, sys_clone (vfork parent), and blocking(). The two IPC channel sites use the split mark_blocked()/yield_now() pair via an action enum.

A condvar-like wrapper that makes the ordering impossible to get wrong:

#![allow(unused)]
fn main() {
/// Single-waiter condvar for kernel blocking.
///
/// Encapsulates the check → register → mark_blocked → unlock → yield cycle.
/// The type system ensures mark_blocked happens before the guard drops.
pub struct WaitCondition;

impl WaitCondition {
    /// If `predicate(guard)` returns true (i.e. "should block"), register
    /// the waiter, mark the thread Blocked, release the lock, and yield.
    /// Returns when unblocked and rescheduled.
    ///
    // [spec: completion_port/completion_port.tla
    //   CheckAndAct (check + set_waiter + mark_blocked) = one label
    //   WaitUnblocked (await running) = next label]
    pub fn wait_while<T, L: Lock<T>>(
        mut guard: L::Guard<'_>,
        predicate: impl Fn(&T) -> bool,
        register: impl FnOnce(&mut T, usize),
    ) {
        if !predicate(&*guard) {
            return; // condition already satisfied, no need to block
        }
        let thread_idx = scheduler::current_thread_idx();
        register(&mut *guard, thread_idx);
        scheduler::mark_blocked();  // mark Blocked while lock held
        drop(guard);                // release lock
        scheduler::yield_now();     // context-switch away; resume after unblock
    }
}
}

Each blocking site reduces to a single call:

#![allow(unused)]
fn main() {
// Completion port
WaitCondition::wait_while(
    port.lock(),
    |p| p.pending() < min,
    |p, idx| p.set_waiter(idx),
);

// Pipe reader
WaitCondition::wait_while(
    self.inner.lock(),
    |inner| inner.buffer.is_empty() && !inner.write_closed,
    |inner, idx| { inner.reader_thread = Some(idx); },
);

// Console input
WaitCondition::wait_while(
    CONSOLE_INPUT.lock(),
    |c| c.buf.is_empty(),
    |c, idx| { c.blocked_reader = Some(idx); },
);

// sys_wait4
WaitCondition::wait_while(
    PROCESS_TABLE.lock(),
    |table| find_zombie_child(table, pid).is_none(),
    |table, idx| {
        table.get_mut(&pid).unwrap().wait_thread = Some(idx);
    },
);
}

Step 5: Deprecate block_current_thread

All three remaining sites (sys_wait4, sys_clone, blocking()) have been migrated. block_current_thread is now unused and can be deprecated. New blocking code must use WaitCondition or the mark_blocked() / yield_now() pair.

Lock ordering note

mark_blocked() acquires the scheduler’s SCHEDULER SpinMutex internally. This means any lock held by the caller must come before SCHEDULER in the lock ordering. The current codebase already satisfies this: all IrqMutex and SpinMutex locks protecting shared state are acquired before (and never after) the scheduler lock.

If a future lock needs to be acquired after the scheduler lock, that lock cannot be held when calling mark_blocked() — use the manual split instead, and mark blocked before acquiring the inner lock.

PlusCal correspondence

Each WaitCondition::wait_while call maps to exactly two PlusCal labels, making formal verification straightforward.

Relation to the io_ring_enter double-lock bug

sys_io_ring_enter phase 3 currently does:

#![allow(unused)]
fn main() {
{ let p = port.lock(); /* check cq_available */ }  // lock 1
{ let mut p = port.lock(); p.set_waiter(idx); }    // lock 2
scheduler::block_current_thread();                  // lock 3
}

The check and set_waiter are under separate locks, so a CQE posted between them is missed. WaitCondition fixes this by construction: the predicate check and waiter registration happen under a single lock acquisition.

Scheduler Donate (Direct-Switch) Infrastructure

Overview

All blocking IPC in ostoo (pipes, completion ports, wait4, vfork) uses unblock(thread_idx) which pushes the woken thread to the back of the ready queue. The thread then waits for the scheduler’s round-robin to reach it — up to 10 ms (full quantum).

The scheduler donate mechanism adds a voluntary yield via a dedicated ISR vector (int 0x50) so the waker can switch to the woken thread immediately, eliminating the up-to-10 ms latency.

Mechanism

Yield interrupt (vector 0x50)

ipc_yield_stub is an assembly handler identical to the LAPIC timer stub (lapic_timer_stub) but calls yield_tick instead of preempt_tick. It provides a software-triggered context switch from syscall context.

yield_tick differs from preempt_tick:

• No tick(), no lapic_eoi() — not a hardware interrupt
• No quantum decrement — always performs the switch
• Checks DONATE_TARGET: AtomicUsize for a direct-switch target

Public API

unblock_yield is the high-level primitive for the pattern: unblock a thread and immediately switch to it.

Direct-switch flow

1. Waker calls unblock(target) — target moves to Ready, pushed to ready queue
2. Waker calls set_donate_target(target) — stores target in atomic
3. Waker calls yield_now() — triggers int 0x50
4. yield_tick saves waker’s state, sees donate target, switches to target
5. Target resumes from its blocked state immediately
6. Waker is re-queued as Ready and runs later via normal scheduling

If the donate target is no longer Ready (e.g., the timer already dispatched it), yield_tick falls back to regular round-robin.

Applied to existing primitives

Pipes (libkernel/src/file.rs)

pipe_wake_reader() returns the woken thread index. PipeWriter::write() drops the pipe lock, then calls set_donate_target + yield_now() if a reader was woken.

PipeWriter::close() returns the woken thread index (if writer_count reaches 0 and a reader was woken). It cannot yield itself because it runs inside with_process() which holds the process table lock. Instead, sys_close yields after the lock is released.

PipeInner tracks writer_count (incremented by on_dup(), decremented by close()). write_closed is set only when writer_count reaches 0, matching Unix pipe semantics where EOF is delivered only after all writer fds are closed.

FdObject::clone() does NOT call on_dup() — it is a plain Arc clone. on_dup() is only called via FdObject::notify_dup() at actual fd-duplication sites (clone/fork fd_table inheritance, dup2).

The pipe lock must be dropped before yielding — otherwise the reader thread would deadlock trying to acquire it.

Completion ports (libkernel/src/completion_port.rs)

CompletionPort::post() returns Option<usize> — the woken waiter thread index. ISR-context callers ignore the return value. Syscall-context callers (e.g., OP_NOP in io_port.rs) use it to yield to the waiter.

Process exit (libkernel/src/process.rs)

terminate_process() calls yield_now() before kill_current_thread(). If the parent has a wait_thread, the donate target is set to the parent’s thread so it returns from wait4 immediately. The dying thread’s remaining quantum is donated to the parent.

Safety constraints

• yield_now() must NOT be called from ISR context. The scheduler lock could deadlock (ISR preempts code holding the lock, ISR tries to acquire lock → deadlock).
• ISR paths (e.g., irq_fd_dispatch → CompletionPort::post()) continue using plain unblock(). This is fine because ISRs are short.
• All locks (pipe, completion port) must be dropped before calling yield_now().

Why int 0x50 works from syscall context

During a SYSCALL handler the CPU runs on the kernel stack with GS = kernel GS (from swapgs in the syscall entry stub). int 0x50 pushes a ring-0 interrupt frame. The yield stub sees RPL = 0 in the saved CS, skips swapgs. Saves all GPRs + FXSAVE. yield_tick saves RSP, switches to target’s stack. Target’s frame (from its own yield or timer preemption) is restored via fxrstor + GPR pops + iretq.

Key files

Signal Support

Current state

Phase 1 of POSIX signal support: basic signal data structures, rt_sigaction, rt_sigprocmask, signal delivery on SYSCALL return, rt_sigreturn, and kill.

What works

• rt_sigaction (syscall 13): install/query signal handlers with SA_SIGINFO and SA_RESTORER
• rt_sigprocmask (syscall 14): SIG_BLOCK, SIG_UNBLOCK, SIG_SETMASK
• kill (syscall 62): send signals to specific pids
• Signal delivery on SYSCALL return path via check_pending_signals
• rt_sigreturn (syscall 15): restore context after signal handler returns
• Default actions: SIG_DFL (terminate or ignore depending on signal), SIG_IGN
• sigaltstack (syscall 131): stub returning 0

Signal delivery mechanism

The SYSCALL assembly stub saves 8 registers onto the kernel stack and stores the stack pointer into PerCpuData.saved_frame_ptr (GS offset 40). After syscall_dispatch returns, check_pending_signals() is called:

1. Peek at process’s pending & !blocked — early return if empty
2. Dequeue lowest pending signal
3. If SIG_DFL: terminate (SIGKILL, SIGTERM, etc.) or ignore (SIGCHLD, SIGCONT)
4. If SIG_IGN: return
5. If handler installed: construct rt_sigframe on user stack, rewrite saved frame

The rt_sigframe on the user stack contains:

• pretcode (8B): sa_restorer address (musl’s __restore_rt)
• siginfo_t (128B): signal number, errno, code
• ucontext_t (224B): saved registers (sigcontext), fpstate ptr, signal mask

The saved SYSCALL frame is rewritten so sysretq “returns” into the handler:

• RCX (→ RIP) = handler address
• RDI = signal number
• RSI = &siginfo (if SA_SIGINFO)
• RDX = &ucontext (if SA_SIGINFO)
• User RSP = rt_sigframe base

When the handler returns, __restore_rt calls rt_sigreturn (syscall 15), which reads the saved context from the rt_sigframe and restores the original registers and signal mask.

Architecture

Key files

PerCpuData layout

saved_frame_ptr is not saved/restored per-thread

saved_frame_ptr lives in a single per-CPU slot and is not saved/restored during context switches. This is safe today because it is set and consumed entirely within the SYSCALL entry/exit path with interrupts disabled:

1. The assembly stub pushes registers, writes mov gs:40, rsp, then calls syscall_dispatch followed by check_pending_signals — all before the register pops and sysretq.
2. rt_sigreturn is itself a syscall, so the stub sets saved_frame_ptr at the start of the same SYSCALL path before sys_rt_sigreturn reads it.

No preemption can occur between setting and consuming the pointer.

If signal delivery is ever needed from interrupt context (e.g. delivering SIGSEGV from a page-fault handler or SIGINT from a keyboard ISR), this design must be revisited — either by saving/restoring saved_frame_ptr per-thread in the scheduler, or by using a different mechanism to locate the interrupted frame (e.g. the interrupt stack frame pushed by the CPU).

Signal-interrupted syscalls (EINTR)

Blocking syscalls (sys_wait4, PipeReader::read) can be interrupted by signals. The mechanism uses a per-process signal_thread field:

1. Before blocking, the syscall stores its scheduler thread index in process.signal_thread.
2. sys_kill, after queuing a signal, reads signal_thread and calls scheduler::unblock() on it if set.
3. When the blocked thread wakes, it checks for pending signals. If any are deliverable (pending & !blocked != 0), it returns EINTR instead of re-blocking.
4. The field is cleared on any exit path (data available, EOF, or signal).

Only interruptible blocking sites set signal_thread. Non-interruptible blocks (vfork parent in sys_clone, blocking() async bridge) never set it, so they remain unaffected.

The shell’s cmd_run handles EINTR from waitpid by forwarding SIGINT to the child process and re-waiting, enabling Ctrl+C to reach child processes running in the terminal.

Future work

• Exception-generated signals (SIGSEGV, SIGILL, SIGFPE from ring-3 faults)
• FPU state save/restore in signal frames
• Signal queuing (currently only one instance per signal — standard signals)

Process Spawning

How user-space processes are created.

Current Implementation

Process creation uses the standard Linux clone(CLONE_VM|CLONE_VFORK) + execve path. musl’s posix_spawn and Rust’s std::process::Command work unmodified.

clone (CLONE_VM | CLONE_VFORK | SIGCHLD)

clone creates a child process that shares the parent’s address space. The parent blocks until the child calls execve or _exit.

See syscalls/clone.md for full details.

execve

execve replaces the current process’s address space with a new ELF binary. Reads the ELF from the VFS, creates a fresh PML4, maps segments, builds the initial stack with argc/argv/envp/auxv, closes FD_CLOEXEC fds, unblocks the vfork parent, and jumps to userspace.

See syscalls/execve.md for full details.

Internal spawning (kernel-side)

For boot-time process creation (e.g. auto-launching the shell), the kernel uses osl::spawn::spawn_process_full(elf_data, argv, envp, parent_pid) which combines ELF loading and process creation in a single call.

kernel/src/ring3.rs provides spawn_process and spawn_process_with_env wrappers that delegate to spawn_process_full.

Process lifecycle

parent: clone(CLONE_VM|CLONE_VFORK)
  │
  │  ┌─── child created (shares parent PML4) ───┐
  │  │                                            │
  │  │  execve("/bin/prog", argv, envp)           │
  │  │    → fresh PML4, ELF mapped                │
  │  │    → close CLOEXEC fds                     │
  │  │    → unblock parent                        │
  │  │    → jump to ring 3                        │
  │  │                                            │
  ├──┘  parent unblocked                          │
  │                                               │
  │  waitpid(child, &status, 0)                   │
  │    → blocks until child exits                 │
  │                                               │
  │  child: _exit(code)                           │
  │    → mark zombie, wake parent                 │
  │                                               │
  ▼  parent: waitpid returns, reap zombie

Key files

Future work

• fork + CoW page faults — full POSIX fork with copy-on-write. Requires page fault handler and per-frame reference counting.
• fd inheritance across clone — currently the child gets a copy of the parent’s fd table; selective inheritance could be added.

Plan: User Space and Process Isolation

Context

The kernel currently runs everything — drivers, shell, filesystem — in a single ring-0 address space as async Rust tasks. This document outlines the path from that baseline to a system where untrusted programs run in isolated ring-3 processes with their own virtual address spaces, communicating with the kernel through system calls, and eventually linked against a ported musl libc.

Progress Summary

Phases 0–6 are complete. The kernel runs a musl-linked C shell (user/shell.c) as its primary user interface. The shell auto-launches on boot, supports line editing, built-in commands (echo, pwd, cd, ls, cat, exit, help), and spawning external programs. Process creation uses standard Linux clone(CLONE_VM|CLONE_VFORK) + execve, enabling unpatched musl posix_spawn and Rust std::process::Command. 35+ syscalls are implemented including pipe2, dup2, fcntl, getpid, getrandom, clone/execve, and custom completion port / IPC syscalls.

What works today

• Userspace shell (user/shell.c): musl-linked C shell compiled via Docker cross-compiler, deployed to disk image at /shell. Auto-launched from kernel/src/main.rs on boot; falls back to kernel shell if not found.
• Line editing in the shell: read char-by-char, echo, backspace, Ctrl+C (cancel line), Ctrl+D (exit on empty line).
• Built-in commands: echo, pwd, cd, ls, cat, exit, help.
• External programs: posix_spawn(path) + waitpid from the shell.
• Raw keypress delivery to userspace via libkernel/src/console.rs: foreground PID routing, blocking read(0), keyboard ISR wakeup.
• Per-process FD table (fds 0–2 = ConsoleHandle); FileHandle trait with ConsoleHandle, VfsHandle, and DirHandle implementations.
• 35+ syscalls implemented (see docs/syscalls/ for per-syscall docs): read, write, open, close, fstat, lseek, mmap, mprotect, munmap, brk, ioctl, writev, exit/exit_group, wait4, getcwd, chdir, arch_prctl, futex, getdents64, set_tid_address, set_robust_list, clone, execve, pipe2, dup2, fcntl, getpid, getrandom, kill, rt_sigaction, rt_sigprocmask, rt_sigreturn, sigaltstack, madvise, sched_getaffinity, clock_gettime, plus custom syscalls for completion ports (501–503), IRQ (504), and IPC channels (505–507).
• open resolves paths relative to process CWD; supports both files (VfsHandle) and directories (DirHandle with O_DIRECTORY).
• getdents64 returns linux_dirent64 structs from DirHandle.
• clone(CLONE_VM|CLONE_VFORK) creates a child sharing the parent’s address space; execve replaces it with a new ELF binary. wait4 blocks parent until child exits/zombies.
• writev (used by musl’s printf) writes scatter/gather buffers to VGA.
• brk grows the process heap by allocating and mapping zero-filled pages.
• mmap supports anonymous MAP_PRIVATE allocations via a bump-down allocator starting at 0x4000_0000_0000.
• Process tracks brk_base/brk_current (computed from ELF segment extents), mmap_next/mmap_regions, fd_table, cwd, parent_pid, wait_thread.
• ELF parser extracts phdr_vaddr, phnum, and phentsize for the auxiliary vector (musl reads AT_PHDR/AT_PHNUM/AT_PHENT during startup).
• spawn_process_full (in osl/src/spawn.rs) builds the initial stack with argc, argv strings, envp (NULL), and auxiliary vector.
• Async-to-sync bridge (osl/src/blocking.rs): spawns async VFS operations as kernel tasks, blocks the user thread, unblocks on completion.
• Unhandled syscalls log a warning with the syscall number and first 3 args, then return -ENOSYS.
• Ring-3 page faults, GPFs, and invalid opcodes log the fault, mark the process zombie, wake the parent’s wait thread, restore kernel GS polarity, and kill the thread — no kernel panic.
• test isolation verifies two independently-created PML4s have genuinely independent user-space mappings at the same virtual address.
• System info commands (cpuinfo, meminfo, memmap, pmap, threads, tasks, idt, pci, lapic, ioapic, drivers, uptime) are exposed as /proc virtual files accessible via cat /proc/<file>.

Key implementation files

Virtual Address Space Layout

The kernel’s heap, APIC, and MMIO window live in the high canonical half (≥ 0xFFFF_8000_0000_0000), so the entire lower canonical half is available for user process address spaces. The kernel/user boundary is enforced at the PML4 level: entries 0–255 (lower half) are user-private; entries 256–510 (high half) are kernel-shared; entry 511 is the per-PML4 recursive self-mapping.

0x0000_0000_0000_0000  ← canonical zero (null pointer trap page, unmapped)
0x0000_0000_0040_0000  ← ELF load address (4 MiB, standard x86-64)
         ↓ text, data, BSS
         ↓ brk heap (grows up from page-aligned end of highest PT_LOAD segment)
         ...
0x0000_4000_0000_0000  ← mmap region (bump-down allocator, grows downward)
         ...
0x0000_7FFF_F000_0000  ← ELF user stack base (8 pages = 32 KiB)
0x0000_7FFF_F000_8000  ← ELF user stack top (RSP starts here minus auxv layout)
0x0000_7FFF_FFFF_FFFF  ← top of lower canonical half (entire range = user)
                         (non-canonical gap)
0xFFFF_8000_0000_0000  ← kernel heap        (HEAP_START, 512 KiB)
0xFFFF_8001_0000_0000  ← Local APIC MMIO    (APIC_BASE)
0xFFFF_8001_0001_0000  ← IO APIC(s)
0xFFFF_8002_0000_0000  ← MMIO window        (MMIO_VIRT_BASE, 512 GiB)
phys_mem_offset         ← bootloader physical memory identity map (high half)
0xFFFF_FF80_0000_0000  ← recursive PT window (PML4[511])
0xFFFF_FFFF_FFFF_F000  ← PML4 self-mapping

Kernel entries (PML4 indices 256–510) are copied into every process page table without USER_ACCESSIBLE; they are invisible to ring-3 code.

Phase 0 — Toolchain and Build Infrastructure ✅ COMPLETE

Goal: produce user-space ELF binaries that the kernel can load, without needing musl yet.

0a. Custom linker script

Write user/link.ld:

ENTRY(_start)
SECTIONS {
  . = 0x400000;
  .text   : { *(.text*) }
  .rodata : { *(.rodata*) }
  .data   : { *(.data*) }
  .bss    : { *(.bss*) COMMON }
}

0b. Rust no_std user target

Add a custom target JSON x86_64-ostoo-user.json with:

• "os": "none", "env": "", "vendor": "unknown"
• "pre-link-args": pass the linker script
• "panic-strategy": "abort" (no unwinding in user space initially)
• "disable-redzone": true (same requirement as kernel)

A minimal user/ crate can implement _start in assembly, call a main, then invoke the exit syscall.

0c. Assembly user programs

Before the ELF loader exists, a hand-crafted binary blob (or raw ELF built from a few lines of NASM) is enough to verify the ring-3 transition and basic syscalls work.

Phase 1 — Ring-3 GDT Segments and SYSCALL Infrastructure ✅ COMPLETE

Goal: the kernel can jump to ring 3 and come back via SYSCALL/SYSRET. No process isolation yet — user code runs in the kernel’s own address space.

What was implemented:

• GDT extended with kernel data, user data, and user code segments in the order required by IA32_STAR (libkernel/src/gdt.rs).
• TSS.rsp0 updated via set_kernel_stack() on every context switch to a user process.
• SYSCALL MSRs (STAR, LSTAR, FMASK, EFER.SCE) configured in libkernel/src/syscall.rs::init().
• Assembly entry stub with swapgs, per-CPU kernel/user RSP swap, and SysV64 argument shuffle before calling syscall_dispatch.
• Three syscalls: write (fd 1/2 to VGA), exit/exit_group (mark zombie + kill thread), arch_prctl(ARCH_SET_FS) (write IA32_FS_BASE MSR).
• Ring-3 test (test ring3): drops to user mode, writes “Hello from ring 3!” via syscall, exits cleanly.

1a. GDT additions (libkernel/src/gdt.rs)

Add four new descriptors in the order required by IA32_STAR:

Index  Selector  Descriptor
  0    0x00      Null
  1    0x08      Kernel code (ring 0, already exists)
  2    0x10      Kernel data (ring 0) ← new; SYSRET expects it at STAR[47:32]+8
  3    0x18      (padding / null for SYSRET alignment)
  4    0x20      User   code (ring 3) ← new; STAR[63:48]
  5    0x28      User   data (ring 3) ← new; at STAR[63:48]+8
  6    0x30+     TSS (2 slots for the 16-byte system descriptor)

IA32_STAR layout: bits 47:32 = kernel CS (SYSCALL), bits 63:48 = user CS − 16 (SYSRET uses this+16 for CS and +8 for SS).

Update the Selectors struct and init() in gdt.rs.

1b. TSS kernel-stack field

When the CPU delivers a ring-3 interrupt it loads RSP from TSS.rsp0. This must point to the current process’s kernel stack top. For now a single global TSS is fine; when processes exist, rsp0 is updated on every context switch.

1c. SYSCALL MSR setup (libkernel/src/interrupts.rs or new libkernel/src/syscall.rs)

#![allow(unused)]
fn main() {
pub fn init_syscall() {
    // IA32_STAR: kernel CS at bits 47:32, user CS-16 at bits 63:48
    let star: u64 = ((KERNEL_CS as u64) << 32) | ((USER_CS as u64 - 16) << 48);
    unsafe { Msr::new(0xC000_0081).write(star); }         // STAR

    // IA32_LSTAR: entry point for 64-bit SYSCALL
    unsafe { Msr::new(0xC000_0082).write(syscall_entry as u64); }

    // IA32_FMASK: clear IF, DF on SYSCALL (but keep other flags)
    unsafe { Msr::new(0xC000_0084).write(0x0000_0300); }  // IF | DF

    // Enable SCE bit in EFER
    let efer = unsafe { Msr::new(0xC000_0080).read() };
    unsafe { Msr::new(0xC000_0080).write(efer | 1); }
}
}

1d. Assembly syscall entry stub

libkernel/src/syscall_entry.asm (or global_asm! in syscall.rs):

syscall_entry:
    swapgs                  ; switch to kernel GS (store user GS)
    mov  [gs:USER_RSP], rsp ; save user RSP into per-cpu area
    mov  rsp, [gs:KERN_RSP] ; load kernel RSP

    push rcx                ; user RIP (SYSCALL saves it here)
    push r11                ; user RFLAGS

    ; push all scratch registers
    push rax
    push rdi
    push rsi
    push rdx
    push r10
    push r8
    push r9

    ; rax = syscall number, rdi/rsi/rdx/r10/r8/r9 = arguments
    mov  rdi, rax
    call syscall_dispatch   ; -> rax = return value

    pop  r9
    pop  r8
    pop  r10
    pop  rdx
    pop  rsi
    pop  rdi
    ; leave rax as return value

    pop  r11                ; restore RFLAGS
    pop  rcx                ; restore user RIP
    mov  rsp, [gs:USER_RSP] ; restore user RSP
    swapgs
    sysretq

swapgs requires a per-CPU data block holding the kernel stack pointer. Implement as a small struct at a known virtual address (or via GS_BASE MSR).

1e. Minimal syscall dispatch table

Start with just three numbers (matching Linux x86-64 for musl compatibility):

1f. First ring-3 test

Write a tiny inline assembly test in kernel/src/main.rs that:

1. Pushes a fake user-mode iret frame (SS, RSP, RFLAGS with IF, CS ring-3, RIP).
2. iretq into ring 3.
3. User code executes syscall with rax=1 (write), prints one character.
4. Kernel writes it to VGA and returns to ring 3.
5. User code executes syscall with rax=60 (exit).

This verifies the GDT, SYSCALL, and basic ABI without an ELF loader or address space isolation.

Phase 2 — Per-Process Page Tables and Address Space Isolation ✅ COMPLETE

Goal: each process has its own PML4; kernel mappings are shared; user mappings are private.

What was implemented:

• MemoryServices::create_user_page_table() allocates a fresh PML4, copies kernel entries (indices 256–510) without USER_ACCESSIBLE, and sets the recursive self-mapping at index 511.
• MemoryServices::map_user_page() maps individual 4 KiB pages in a non-active page table given its PML4 physical address.
• unsafe switch_address_space(pml4_phys) writes CR3.
• Page fault handler (libkernel/src/interrupts.rs) checks stack_frame.code_segment.rpl() — ring-3 faults mark the process zombie (exit code -11 / SIGSEGV), restore kernel GS via swapgs, and call kill_current_thread(). Kernel faults still panic.
• test isolation shell command verifies two PML4s map the same user virtual address to different physical frames.
• Scheduler preempt_tick saves/restores CR3 when switching between threads with different page tables.

2a. Page table creation (libkernel/src/memory/)

Add to MemoryServices:

#![allow(unused)]
fn main() {
/// Allocate a fresh PML4, copy all kernel PML4 entries (indices where
/// virtual_address >= KERNEL_SPLIT) into it, and return the physical
/// address of the new PML4 frame.
pub fn create_user_page_table(&mut self) -> PhysAddr;

/// Map a single 4 KiB page in a specific (possibly non-active) page table.
pub fn map_user_page(
    &mut self,
    pml4_phys: PhysAddr,
    virt: VirtAddr,
    phys: PhysAddr,
    flags: PageTableFlags,   // USER_ACCESSIBLE | PRESENT | WRITABLE | NO_EXECUTE as needed
) -> Result<(), MapToError<Size4KiB>>;

/// Switch the active address space.  Must be called with interrupts disabled.
pub unsafe fn switch_address_space(&self, pml4_phys: PhysAddr);
}

2b. Kernel/user PML4 split

The layout gives a clean hardware-level split:

• PML4 indices 0–255 (lower canonical half, 0x0000_*) — user-private. Left empty at process creation; populated by the ELF loader and mmap.
• PML4 indices 256–510 (high canonical half, 0xFFFF_8000_* through 0xFFFF_FF7F_*) — kernel-shared. Copied from the kernel PML4 at process creation; marked present but never USER_ACCESSIBLE.
• PML4 index 511 — the recursive self-mapping. Each process PML4 must have its own entry here pointing to its own physical PML4 frame (not the kernel’s). create_user_page_table must set this explicitly.

2c. Page fault handler upgrade

Replace the panic in page_fault_handler with:

#![allow(unused)]
fn main() {
extern "x86-interrupt" fn page_fault_handler(frame: InterruptStackFrame, ec: PageFaultErrorCode) {
    let faulting_addr = Cr2::read();
    if frame.code_segment.rpl() == PrivilegeLevel::Ring3 {
        // Fault in user space — kill the process (deliver SIGSEGV later).
        kill_current_process(Signal::Segv);
        schedule_next();       // does not return to faulting instruction
    } else {
        panic!("kernel page fault at {:?}\n{:#?}\n{:?}", faulting_addr, frame, ec);
    }
}
}

This is the minimum needed to prevent a kernel panic when user code accesses invalid memory; proper CoW / demand paging comes later.

2d. Address space switch on context switch

The scheduler’s preempt_tick function currently saves/restores only kernel RSP. Extend it to also write CR3 when switching between processes with different page tables.

Phase 3 — Process Abstraction ✅ COMPLETE

Goal: Process struct, a process table, and a working exec.

What was implemented:

• Process struct (libkernel/src/process.rs) with PID, state (Running/Zombie), PML4 physical address, heap-allocated 64 KiB kernel stack, entry point, user stack top, thread index, and exit code.
• Global PROCESS_TABLE: Mutex<BTreeMap<ProcessId, Process>> and CURRENT_PID: AtomicU64.
• insert(), current_pid(), set_current_pid(), with_process(), mark_zombie(), reap(), reap_zombies().
• Scheduler integration: SchedulableKind::Kernel | UserProcess(ProcessId). spawn_user_thread creates a thread targeting process_trampoline which sets up TSS.rsp0, per-CPU kernel RSP, PID tracking, GS polarity, CR3 switch, and then does iretq into ring-3 user code.
• kill_current_thread() marks the thread Dead and spins; timer preemption skips dead threads.
• ELF loader (libkernel/src/elf.rs): minimal parser for static ET_EXEC x86-64 binaries. Returns ElfInfo { entry, segments, phdr_vaddr, phnum, phentsize }.
• kernel/src/ring3.rs::spawn_process(elf_data) — parses ELF, creates user PML4, maps all PT_LOAD segments (with correct R/W/X flags) plus a user stack page, creates a Process, and spawns a user thread. Returns Ok(ProcessId).
• Shell command exec <path> reads an ELF from the VFS and calls spawn_process.
• spawn_blob(code) helper for test commands: maps a raw code blob + stack, creates a Process, spawns a user thread.
• Zombie reaping: reap_zombies() is called at the start of spawn_blob and spawn_process to free kernel stacks of fully-exited processes.

3a. Process struct (libkernel/src/process/mod.rs)

#![allow(unused)]
fn main() {
pub struct Process {
    pub pid:           ProcessId,
    pub state:         ProcessState,          // Running, Ready, Blocked, Zombie
    pub pml4_phys:     PhysAddr,              // physical address of PML4
    pub kernel_stack:  Vec<u8>,               // 64 KiB kernel stack
    pub saved_rsp:     u64,                   // kernel RSP when not running
    pub user_rsp:      u64,                   // user RSP (restored on ring-3 return)
    pub files:         FileTable,             // open file descriptors
    pub parent:        Option<ProcessId>,
    pub exit_code:     Option<i32>,
}
}

3b. Process table

#![allow(unused)]
fn main() {
lazy_static! {
    static ref PROCESSES: Mutex<BTreeMap<ProcessId, Process>> = ...;
}
}

CURRENT_PID: AtomicU32 — the PID running on each CPU (single-CPU for now).

3c. Scheduler integration

Replace the bare Thread list in scheduler.rs with process-aware scheduling:

• On preempt_tick: save user context (if coming from ring 3), switch CR3, load next process’s user context and kernel RSP.
• TSS.rsp0 updated to point to the new process’s kernel stack top.

3d. ELF loader (libkernel/src/elf.rs)

#![allow(unused)]
fn main() {
pub fn load_elf(
    bytes: &[u8],
    process: &mut Process,
    mem: &mut MemoryServices,
) -> Result<VirtAddr, ElfError>   // returns entry point
}

Steps:

1. Validate ELF magic, e_machine == EM_X86_64, e_type == ET_EXEC (static) or ET_DYN (PIE).
2. For each PT_LOAD segment: allocate physical frames, map at p_vaddr with USER_ACCESSIBLE and flags derived from p_flags (R/W/X).
3. Copy p_filesz bytes from the ELF image; zero-fill to p_memsz.
4. Allocate and map a user stack (8–16 pages) just below the stack top.
5. Set up the initial stack frame: argc=0, argv=NULL, envp=NULL, auxv entries for AT_ENTRY, AT_PHDR, AT_PAGESZ (required by musl’s _start).
6. Return e_entry.

3e. sys_execve syscall

#![allow(unused)]
fn main() {
fn sys_execve(path: *const u8, argv: *const *const u8, envp: *const *const u8) -> ! {
    let bytes = vfs::read_file(path_str).expect("exec: read failed");
    let process = current_process_mut();
    process.reset_address_space();          // drop old page table
    let entry = load_elf(&bytes, process, &mut memory());
    switch_to_user(entry, process.user_stack_top);   // does not return
}
}

Phase 4 — System Call Layer ✅ COMPLETE

Goal: a syscall table wide enough to run a static musl binary that prints “Hello, world!” and exits.

What was implemented:

4a. ELF parser extensions (libkernel/src/elf.rs)

ElfInfo now includes phdr_vaddr, phnum, and phentsize. The parser looks for a PT_PHDR program header (type 6) to get the phdr virtual address directly; fallback computes it from the PT_LOAD segment containing e_phoff. These values populate the auxiliary vector that musl reads during startup.

4b. Process memory tracking (libkernel/src/process.rs)

Process gained four new fields:

Process::new() now takes a brk_base parameter. spawn_process computes it from max(seg.vaddr + seg.memsz) page-aligned up.

4c. Initial stack layout (kernel/src/ring3.rs)

ELF processes get an 8-page (32 KiB) contiguous stack at 0x7FFF_F000_0000, allocated via alloc_dma_pages(8) so the auxv layout can be written through the kernel’s phys_mem_offset window. build_initial_stack() writes:

[stack_top]
  16 bytes pseudo-random data (AT_RANDOM target)
  alignment padding (8 bytes)
  AT_NULL (0, 0)
  AT_RANDOM (25, addr)
  AT_ENTRY (9, entry_point)
  AT_PHNUM (5, phnum)
  AT_PHENT (4, phentsize)
  AT_PHDR (3, phdr_vaddr)
  AT_PAGESZ (6, 4096)
  AT_UID (11, 0)
  NULL                    ← envp terminator
  NULL                    ← argv terminator
  0                       ← argc = 0
[RSP points here, 16-byte aligned]

4d. Syscall table (osl/src/syscalls/mod.rs)

All syscalls use Linux x86-64 numbers for musl compatibility. Unhandled numbers log a warning and return -ENOSYS. Errno constants are defined in osl/src/errno.rs; libkernel uses FileError for structured errors.

Lock ordering for brk and mmap: process table lock acquired/released to read state, then memory lock for frame allocation and page mapping, then process table lock re-acquired to write updates. This avoids nested lock deadlocks.

See docs/syscalls/ for detailed per-syscall documentation.

4e. What’s still missing (deferred to later phases)

• SMAP enforcement: User pointers in writev, fstat, brk are accessed without stac/clac.
• Page deallocation: ✅ Fixed — munmap frees frames and splits VMAs; brk shrink unmaps and frees pages; process exit cleans up the entire user address space.
• mprotect: ✅ Fixed — updates page table flags for the target VMA range.
• FS_BASE save/restore: ✅ Fixed — FS_BASE is saved/restored per-thread in preempt_tick via save_current_context / restore_thread_state.

Phase 5 — Cross-Compiler and musl Port ✅ COMPLETE

Goal: compile C programs that run as ostoo user processes.

What was implemented:

• Docker-based build environment (scripts/user-build.sh) using x86_64-linux-musl-cross toolchain.
• user/Makefile compiles *.c files to static musl-linked ELF binaries.
• user/shell.c is the primary musl binary (see Phase 6).
• Binaries are deployed to the exFAT disk image or shared via virtio-9p.

5a. Toolchain strategy

The simplest path: use an existing x86_64-linux-musl sysroot unmodified, because we implement Linux-compatible syscall numbers (Phase 4). musl does not inspect the OS name at runtime — it just issues syscalls.

Option A (quickest): install x86_64-linux-musl-gcc from musl.cc or via brew install x86_64-linux-musl-cross. Compile with:

x86_64-linux-musl-gcc -static -o hello hello.c

The resulting fully-static ELF should work on ostoo with the Phase 4 syscalls.

Option B (custom triple): build musl from source with a custom --target configured for ostoo. This is useful once ostoo diverges from Linux’s ABI (e.g. custom syscall numbers or a different startup convention).

5b. musl build recipe (Option B outline)

# Prerequisites: a bare x86_64-elf-gcc cross-compiler (via crosstool-ng or
# manual binutils + gcc build targeting x86_64-unknown-elf).

git clone https://git.musl-libc.org/cgit/musl
cd musl
./configure \
  --target=x86_64 \
  --prefix=/opt/ostoo-sysroot \
  --syslibdir=/opt/ostoo-sysroot/lib \
  CROSS_COMPILE=x86_64-elf-
make -j$(nproc)
make install

Key musl files:

• arch/x86_64/syscall_arch.h — __syscall0…__syscall6 use the syscall instruction; no changes needed if syscall numbers match Linux.
• crt/x86_64/crt1.o — _start sets up argc/argv/envp from the initial stack (ABI defined in the ELF auxiliary vector; match what the ELF loader sets up in Phase 3d).
• src/env/__init_tls.c — calls arch_prctl(ARCH_SET_FS, ...); requires the sys_arch_prctl syscall (Phase 4b).

5c. Rust user programs

For Rust programs targeting ostoo, add a custom target x86_64-ostoo-user.json (from Phase 0b) and a minimal ostoo-rt crate that:

• Provides _start (sets up a stack frame; calls main; calls sys_exit).
• Provides #[panic_handler] that calls sys_exit(1).
• Wraps the small syscall ABI.

Users can then write:

#![no_std]
#![no_main]
extern crate ostoo_rt;

#[no_mangle]
pub extern "C" fn main() {
    ostoo_rt::write(1, b"Hello from Rust!\n");
}

Phase 6 — Spawn, Wait, and a Minimal Shell ✅ COMPLETE

Goal: a user-mode shell that can launch and wait for child programs.

What was implemented:

Process creation uses the standard Linux clone(CLONE_VM|CLONE_VFORK) + execve path. musl’s posix_spawn and Rust’s std::process::Command work unmodified.

6a. clone (syscall 56)

clone(CLONE_VM|CLONE_VFORK|SIGCHLD) creates a child sharing the parent’s address space. The parent blocks until the child calls execve or _exit.

See clone.

6b. execve (syscall 59)

Replaces the current process image with a new ELF binary. Reads from VFS, creates a fresh PML4, maps segments, builds the initial stack, closes CLOEXEC fds, unblocks the vfork parent, and jumps to userspace.

See execve.

6c. wait4 (syscall 61)

• sys_wait4(pid, status_ptr, options) — find zombie child, write exit status, reap, return child PID
• If no zombie found: register wait_thread on parent, block, retry on wake
• sys_exit wakes parent’s wait_thread via scheduler::unblock()

6d. Userspace shell (user/shell.c)

• Compiled with musl (static), deployed at /shell
• Line editing: read char-by-char, echo, backspace, Ctrl+C, Ctrl+D
• Built-in commands: echo, pwd, cd, ls, cat, exit, help
• External programs: posix_spawn(path) + waitpid(child, &status, 0)
• Auto-launched from kernel/src/main.rs; falls back to kernel shell if /shell is not found on the filesystem

6e. What’s deferred

• fork + CoW page faults — standard POSIX fork is not implemented. Adding it would require: marking all user pages read-only in both parent and child, a CoW page fault handler that copies on write, and reference counting on physical frames.

Phase 7 — Signals ⬜ NOT STARTED

Signals are the last major piece of POSIX plumbing needed for a realistic user-space environment.

Minimal signal implementation

#![allow(unused)]
fn main() {
pub struct SigAction { handler: usize, flags: u32, mask: SigSet }
pub struct SigTable  { actions: [SigAction; 32], pending: SigSet, masked: SigSet }
}

• sys_rt_sigaction installs handlers.
• Before returning to user space after a syscall or interrupt, check pending & ~masked.
• If set: push a signal frame on the user stack (siginfo + ucontext), set RIP to the handler, clear the pending bit.
• sys_rt_sigreturn: the signal handler calls this when done; the kernel pops the ucontext and resumes normal user execution.

Dependency Graph

Phase 0 ✅ ← Phase 1 ✅ ← Phase 2 ✅ ← Phase 3 ✅ ← Phase 4 ✅ ← Phase 5 ✅ ← Phase 6 ✅
(toolchain)   (ring-3,       (address     (Process,        (syscall        (musl)       (spawn/wait/
               syscall)       spaces)      ELF loader)      layer)                       shell)
                                                                                  ↓
                                                                           Phase 7 (signals)

Key Risks and Design Decisions

SYSCALL vs INT 0x80

Use SYSCALL/SYSRET (64-bit, fast path). INT 0x80 is the 32-bit ABI; musl uses SYSCALL on x86-64 exclusively.

Kernel/user split

The kernel lives entirely in the high canonical half (0xFFFF_8000_* and above): heap at 0xFFFF_8000_*, APIC at 0xFFFF_8001_*, MMIO window at 0xFFFF_8002_*. The entire lower canonical half is free for user processes. The split is enforced at the PML4 level — user processes simply have no mappings at indices 256–510, and the kernel entries they inherit are never USER_ACCESSIBLE. SMEP (CR4.20) and SMAP (CR4.21) provide the hardware enforcement layer once ring-3 processes exist.

SMEP and SMAP

Once ring-3 processes exist, enable SMEP (CR4.20) to prevent the kernel from accidentally executing user-mapped code, and SMAP (CR4.21) to prevent the kernel from silently accessing user memory without an explicit stac/clac pair. Any kernel code that copies from user buffers must use a checked copy function that uses stac to temporarily permit access.

Static-only ELF initially

Dynamic linking requires an in-kernel or user-space ELD interpreter. Start with -static binaries and the ELF loader described in Phase 3d. PIE static binaries (ET_DYN with no INTERP segment) should work with minor adjustments to the loader.

Single CPU for now

The process table and scheduler assume a single CPU. SMP support would require per-CPU CURRENT_PID, per-CPU kernel stacks in the TSS, and IPI-based TLB shootdown when modifying another process’s page table.

Heap size

The kernel heap is 1 MiB. Process control blocks each consume 64 KiB (kernel stack) plus page table frames, plus Vec storage for mmap_regions. Zombie processes are reaped via wait4 + reap(), but loading multiple concurrent processes will still pressure the heap.

Memory management

munmap frees frames and splits/removes VMAs. brk shrink frees pages. Process exit calls cleanup_user_address_space to walk and free all user-half page tables and frames. The kernel heap (1 MiB) is the main remaining pressure point for concurrent processes.

Milestones and Test Checkpoints

read (nr 0)

Linux Signature

ssize_t read(int fd, void *buf, size_t count);

Description

Reads up to count bytes from file descriptor fd into buf.

Current Implementation

Looks up fd in the current process’s per-process file descriptor table and calls FileHandle::read() on the handle.

• fd 0 (stdin) — ConsoleHandle: Reads raw bytes from the console input buffer (libkernel/src/console.rs). If the buffer is empty, blocks the current scheduler thread via block_current_thread() until the keyboard ISR delivers input via push_input(). Returns at least 1 byte per call.
• VFS file fds — VfsHandle: Reads from an in-memory buffer loaded at open() time. Maintains a per-handle read position. Returns 0 at EOF.
• Directory fds — DirHandle: Returns -EISDIR (-21).
• Invalid fds: Returns -EBADF (-9).

Validates that buf falls within user address space (< 0x0000_8000_0000_0000). Returns -EFAULT (-14) on invalid pointers. Returns 0 immediately if count is 0.

Source: osl/src/syscalls/io.rs — sys_read

Future Work

• Support partial reads and proper error handling for VFS files.
• SMAP enforcement for user buffer validation.

write (nr 1)

Linux Signature

ssize_t write(int fd, const void *buf, size_t count);

Description

Writes up to count bytes from buf to file descriptor fd.

Current Implementation

Looks up fd in the current process’s per-process file descriptor table and calls FileHandle::write() on the handle.

• fd 1 (stdout) and fd 2 (stderr) — ConsoleHandle: Interprets buf as UTF-8 and prints to the VGA text buffer via print!(). If not valid UTF-8, falls back to printing printable ASCII (0x20..0x7F) plus \n, \r, \t. Returns count on success.
• VFS file fds — VfsHandle: Returns -EBADF (-9) — files are read-only.
• Invalid fds: Returns -EBADF (-9).

Validates that buf falls within user address space (< 0x0000_8000_0000_0000). Returns -EFAULT (-14) on invalid pointers.

Source: osl/src/syscalls/io.rs — sys_write

Future Work

• Support writable VFS files.
• Handle partial writes.

open (nr 2)

Linux Signature

int open(const char *pathname, int flags, mode_t mode);

Description

Opens a file or directory at pathname and returns a file descriptor.

Current Implementation

1. Reads a null-terminated path string from user space (max 4096 bytes). Returns -EFAULT if the pointer is invalid.
2. Resolves the path relative to the process’s current working directory (cwd). Normalises . and .. components.
3. Unless O_DIRECTORY (0o200000) is set, first attempts to open as a file via devices::vfs::read_file() (through osl::blocking::blocking()). On success, the entire file content is loaded into a VfsHandle (buffered in kernel memory) and a new fd is allocated.
4. If the file open fails with VfsError::NotFound or VfsError::NotAFile, or O_DIRECTORY was requested, falls back to opening as a directory via devices::vfs::list_dir(). On success, creates a DirHandle with the directory listing and allocates a new fd.
5. Returns the new fd number on success, or a negative errno.

The VFS operations use osl::blocking::blocking() which spawns the async VFS call as a kernel task and blocks the calling user thread until it completes.

Flags supported: O_DIRECTORY (to explicitly request directory). O_RDONLY is implied for all opens. Other flags are accepted but ignored.

Source: osl/src/syscalls/fs.rs — sys_open

Errors

Future Work

• Support O_WRONLY, O_CREAT, O_TRUNC for writable files.
• Streaming reads instead of loading entire file into memory at open time.
• Proper mode handling.