ITISYOU_OS
PRE-ALPHA

System Architecture

What exists now and the boundaries later milestones build inside. Anything marked PLANNED or CONCEPT is design intent, not implemented functionality.

LAYER 00

Virtual Platform

QEMU is the only supported execution environment for V0.1. Physical hardware boot is intentionally out of scope and untested.

  • > qemu-system-x86_64 (single CPU, no SMP)
  • > SeaBIOS / OVMF-UEFI firmware
  • > project-generated disposable disk images only

LAYER 01

Boot Layer

rust-osdev bootloader crate (BIOS & UEFI stages) hands the kernel a typed BootInfo: memory regions, physical-memory mapping offset, framebuffer, RSDP. Boot-time-only code — not part of the OS runtime.

VERIFIED

LAYER 02 RING_0

Kernel Space

All Rust no_std code in kernel/ — the trusted computing base. The kernel runs ring 0 inside QEMU; as of V0.2 it hosts one Ring 3 process at a time behind MMU-enforced separation.

BOOT HANDOFF

typed BootInfo → early_init

VERIFIED

SERIAL / STAGES

COM1 markers, pre-allocator

VERIFIED

CPU BASELINE

vendor/features identification

VERIFIED

MEMORY

memory map → PMM → paging → heap

VERIFIED

DESCRIPTORS / IRQ

GDT/TSS/IDT → PIC/PIT timer

VERIFIED

TASKS / FS / SHELL

scheduler → VFS/initramfs → shell

VERIFIED

Panic on violated invariants; panics emit [ITISYOU:PANIC] and fail test runs deterministically.

FUTURE SECURITY BOUNDARY

Policy / Capability Engine

Documented direction: privileged operations sit behind a deterministic policy and service layer, so a future AI agent can propose actions but never execute kernel operations directly.

CONCEPT No AI in the V0.1 runtime

LAYER 03 RING_3

Userspace

Ring 3 execution with a validated syscall ABI (V0.2): real ELF64 programs, user pointers checked before any kernel dereference, no user mapping of kernel pages, faults contained to the process. One process at a time — per-process page tables for concurrent processes are the next step.

VERIFIED

Crate boundaries

kernel/

The only privileged code

Library + two binaries: itisyou-kernel (interactive) and itisyou-kernel-selftest (boots, runs in-kernel checks, exits QEMU with a deterministic status).

crates/kernel-core

Pure logic, zero I/O

Boot-stage contract, serial-marker grammar, and (as subsystems land) memory-map normalization, path handling, parsers. Compiled unchanged into both the kernel and host tools; unit-tested on the host.

tools/image-builder

Host tool

Turns kernel ELFs into bootable BIOS/UEFI disk images (pure Rust) plus a SHA-256 manifest.

tools/qemu-runner

Host test harness

Launches QEMU, asserts boot-stage markers, classifies panic/timeout/selftest outcomes, writes JSON evidence. Absence of output is never success.

Boot contract & observability

Kernel code consumes boot data through itisyou_kernel::early_init, so subsystems never depend on third-party boot structures directly. Serial (COM1) is the primary channel and works before any allocator exists.

// marker grammar — kernel-core::marker (specification)

[ITISYOU:<TAG>] payload

TAG ∈ { B###, PANIC, SELFTEST, TEST, INFO, MODE }

// single source of truth shared by emitter and asserter

Boot-Stage Contract B000 → B150 kernel-core::stage · serial markers

Each stage emits one machine-parseable serial marker — [ITISYOU:B0xx] description — asserted in order by the QEMU harness. Stage statuses below are the live module statuses, not a boot capture.

  1. B000 firmware/loader handoff observed VERIFIED
  2. B010 kernel entry reached in 64-bit mode VERIFIED
  3. B020 early serial console ready VERIFIED
  4. B030 CPU baseline established VERIFIED
  5. B040 boot memory map validated VERIFIED
  6. B050 physical memory manager ready VERIFIED
  7. B060 virtual memory abstraction ready VERIFIED
  8. B070 kernel heap ready VERIFIED
  9. B080 descriptor/exception layer ready VERIFIED
  10. B090 interrupt controller/timer ready VERIFIED
  11. B100 scheduler initialized VERIFIED
  12. B110 VFS/initramfs initialized VERIFIED
  13. B120 input path initialized VERIFIED
  14. B130 shell/init task running VERIFIED
  15. B140 userspace transition ready VERIFIED
  16. B150 V0.1 boot acceptance reached VERIFIED

Planned next boundaries

Dependency order for the kernel subsystems — each lands with host tests and QEMU selftests before the next begins:

  1. physical memory manager
  2. paging abstraction
  3. heap
  4. descriptors/interrupts
  5. scheduler
  6. VFS/initramfs
  7. shell
Full architecture doc