Architecture Overview

High-level architecture of Aegis OS: kernel subsystems, security model, userspace stack, and system diagram

Architecture Overview

Aegis is a monolithic x86_64 operating system written primarily in C with a Rust capability validation subsystem and a custom userspace stack. It targets the Multiboot2 boot protocol, runs on both BIOS and UEFI (via GRUB), and provides a full POSIX-like environment with capability-based security, a TCP/IP network stack, multiple filesystem implementations, SMP support, and a custom GUI composed of a display server, widget toolkit, and desktop shell.

System Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│                           User Space (Ring 3)                           │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                        GUI Stack                                │    │
│  │  ┌───────────┐  ┌─────────────┐  ┌───────────┐  ┌──────────┐    │    │
│  │  │  Citadel  │  │    Lumen    │  │  Bastion  │  │  Glyph   │    │    │
│  │  │ (desktop  │  │(compositor/ │  │ (display  │  │ (widget  │    │    │
│  │  │  shell)   │  │ display srv)│  │  manager) │  │ toolkit) │    │    │
│  │  └───────────┘  └─────────────┘  └───────────┘  └──────────┘    │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
│  ┌────────────┐ ┌─────────┐ ┌────────┐ ┌──────┐ ┌──────┐ ┌──────────┐   │
│  │   Vigil    │ │  stsh   │ │  httpd │ │ dhcp │ │ curl │ │coreutils │   │
│  │(init/svc   │ │(secure  │ │(web    │ │(DHCP │ │(HTTP │ │ls cat cp │   │
│  │ manager)   │ │ shell)  │ │server) │ │client│ │client│ │mv rm ... │   │
│  └────────────┘ └─────────┘ └────────┘ └──────┘ └──────┘ └──────────┘   │
│                                                                         │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                     musl libc 1.2.5 (shared)                     │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                         │
├══════════════════════════ SYSCALL Boundary ═════════════════════════════┤
│                                                                         │
│                          Kernel Space (Ring 0)                          │
│                                                                         │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                     Syscall Dispatch Layer                       │   │
│  │  sys_io · sys_memory · sys_process · sys_exec · sys_identity     │   │
│  │  sys_cap · sys_time · sys_file · sys_dir · sys_meta · sys_signal │   │
│  │  sys_socket · sys_random · sys_disk · futex                      │   │
│  └──────────────────────────────────────────┬───────────────────────┘   │
│                                             │                           │
│  ┌───────────────────────────────────────┐  │  ┌─────────────────────┐  │
│  │        Capability Subsystem           │◄─┘  │  Process Manager    │  │
│  │  cap_init · cap_grant · cap_check     │     │  proc · ELF loader  │  │
│  │  cap_policy (C) + libcap.a (Rust)     │     │  fork · exec · wait │  │
│  └───────────────────────────────────────┘     └─────────────────────┘  │
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                    Virtual File System (VFS)                      │  │
│  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌───────┐ ┌──────┐ ┌──────┐ ┌──────┐  │  │
│  │  │ ext2 │ │ramfs │ │procfs│ │initrd │ │memfd │ │ pipe │ │ pty  │  │  │
│  │  └──────┘ └──────┘ └──────┘ └───────┘ └──────┘ └──────┘ └──────┘  │  │
│  │  + console · kbd_vfs · blkdev · GPT                               │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                         │
│  ┌──────────────────────┐  ┌─────────────────────────────────────────┐  │
│  │   Network Stack      │  │            Scheduler                    │  │
│  │  eth · ip · arp      │  │  Round-robin · wait queues · SMP        │  │
│  │  tcp · udp · icmp    │  │  context switch · idle task             │  │
│  │  socket · unix_socket│  │                                         │  │
│  │  epoll               │  │                                         │  │
│  └──────────┬───────────┘  └─────────────────────────────────────────┘  │
│             │                                                           │
│  ┌──────────┴────────────┐  ┌────────────────────────────────────────┐  │
│  │   Device Drivers      │  │       Memory Management                │  │
│  │  NVMe · xHCI · USB    │  │  PMM (bitmap) · VMM (4-level paging)   │  │
│  │  virtio-net · RTL8169 │  │  KVA (kernel virtual) · VMA (user)     │  │
│  │  framebuffer · ramdisk│  │                                        │  │
│  └───────────────────────┘  └────────────────────────────────────────┘  │
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                    Architecture Layer (x86_64)                    │  │
│  │  boot · GDT · IDT · PIC/LAPIC/IOAPIC · PIT · ACPI · PCIe          │  │
│  │  SYSCALL/SYSRET · SMAP/SMEP · SMP (AP trampoline) · serial/VGA    │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Boot Sequence

The kernel boots via the Multiboot2 protocol. GRUB loads the kernel ELF plus two modules (rootfs image, ESP image) into physical memory.

GRUB → boot.asm (32-bit) → GDT → Long Mode → Page Tables → boot.asm (64-bit)
  → kernel_main()

Initialization Order

kernel_main() executes a strict, sequential initialization of all subsystems:

Phase Subsystem Function Log Marker
1 Architecture arch_init() [SERIAL] OK, [VGA] OK
2 PAT MSR arch_pat_init() (silent)
3 Memory map arch_mm_init() Parses Multiboot2 memory map + cmdline
4 Physical memory pmm_init() [PMM] OK
5 Virtual memory vmm_init() [VMM] OK
6 Kernel allocator kva_init() [KVA] OK
7 Framebuffer fb_init() [FB] OK or silent
8 Capability system cap_init() [CAP] OK
9 Per-CPU data smp_percpu_init_bsp() (silent)
10 Interrupts idt_init(), pic_init() [IDT] OK, [PIC] OK
11 Timer pit_init() [PIT] OK (100 Hz)
12 Input kbd_init(), ps2_mouse_init() [KBD] OK, [MOUSE] OK
13 Ring 3 support arch_gdt_init(), arch_tss_init(), arch_syscall_init() [GDT] OK, [TSS] OK, [SYSCALL] OK
14 CPU security arch_smap_init(), arch_smep_init() [SMAP] OK, [SMEP] OK
15 SSE arch_sse_init() (silent)
16 RNG random_init() [RNG] OK (ChaCha20 CSPRNG)
17 Block devices ramdisk_init() [RAMDISK] OK
18 VFS + initrd vfs_init() [VFS] OK, [INITRD] OK
19 Console console_init() (silent)
20 ACPI acpi_init() [ACPI] OK
21 APIC lapic_init(), ioapic_init() [LAPIC] OK, [IOAPIC] OK
22 PCIe pcie_init() [PCIE] OK
23 Storage nvme_init(), gpt_scan() [NVME] OK, [GPT] OK
24 Root FS ext2_mount() [EXT2] OK
25 Security policy cap_policy_load() [CAP_POLICY] OK
26 Self-tests poll_test() [POLL] OK
27 USB xhci_init() [XHCI] OK
28 Network virtio_net_init(), rtl8169_init(), net_init() [NET] OK
29 SMP smp_start_aps() [SMP] OK
30 Scheduler sched_init(), sched_spawn(task_idle) (silent)
31 Init process proc_spawn_init() Spawns PID 1 (Vigil)
32 Cleanup vmm_teardown_identity() [VMM] OK: identity map removed
33 Go sched_start() [SCHED] OK – never returns

After sched_start(), the idle task enables the LAPIC timer and begins the preemptive multitasking loop. Control never returns to kernel_main().

Boot Modes

The kernel command line (boot=graphical|text, quiet) controls:

  • boot=graphical quiet: Boot splash, printk suppressed on framebuffer, starts Bastion graphical greeter
  • boot=text quiet: No splash, text-mode TTY login
  • boot=text: Verbose output, text-mode login (debug mode)

Memory Management

Aegis implements a four-component memory management system:

Physical Memory Manager (PMM)

Bitmap allocator initialized from the Multiboot2 memory map. Manages all physical page frames (4 KB granularity).

Virtual Memory Manager (VMM)

4-level x86_64 page tables (PML4 → PDP → PD → PT). The kernel occupies the higher half at 0xFFFFFFFF80000000. During early boot, an identity map (PML4[0]) is maintained for the 32-bit trampoline; it is torn down after all initialization is complete.

Kernel Virtual Allocator (KVA)

Manages the kernel’s virtual address space for dynamic allocations: task stacks, per-CPU data, DMA buffers, and mapped device memory.

Virtual Memory Areas (VMA)

Per-process user-space virtual memory management. Handles mmap, brk, stack growth, and copy-on-write semantics for fork.

Capability-Based Security

The security model is the defining feature of Aegis. Every process carries a capability table (64 slots) that determines what operations it may perform. The system uses a two-tier model:

Architecture

┌──────────────────────────────────────────────────┐
│                  Syscall Entry                   │
│                                                  │
│  sys_open() ──► cap_check(proc, CAP_KIND_FS,     │
│                           CAP_RIGHTS_READ)       │
│                     │                            │
│                     ▼                            │
│  ┌─────────────────────────────────────┐         │
│  │     libcap.a (Rust, #[no_std])      │         │
│  │                                     │         │
│  │  cap_grant(table, n, kind, rights)  │         │
│  │  cap_check(table, n, kind, rights)  │         │
│  │                                     │         │
│  │  Validates slot table, returns 0    │         │
│  │  or -ENOCAP (130)                   │         │
│  └─────────────────────────────────────┘         │
│                     │                            │
│                     ▼                            │
│  ┌─────────────────────────────────────┐         │
│  │    cap_policy.c (C policy engine)   │         │
│  │                                     │         │
│  │  Loads /etc/aegis/caps.d/ at boot   │         │
│  │  Assigns baseline capabilities      │         │
│  │  Inherits/restricts on fork/exec    │         │
│  └─────────────────────────────────────┘         │
└──────────────────────────────────────────────────┘
  • Rust validation (kernel/cap/src/lib.rs): The core cap_grant and cap_check functions are written in Rust (#[no_std], compiled to libcap.a for the x86_64-unknown-none target). This provides memory safety guarantees for the security-critical validation path.
  • C policy engine (kernel/cap/cap_policy.c): Loads capability policy files from the rootfs, assigns baseline capabilities to the init process, and manages capability inheritance across fork/exec.

Capability Flow

  1. Boot: cap_policy_load() reads /etc/aegis/caps.d/ and assigns baseline capabilities plus policy capabilities to the init process
  2. Fork: Child inherits parent’s capability table (copy)
  3. Exec: Capability table is reset to 6 baseline capabilities, then augmented with policy capabilities from /etc/aegis/caps.d/ based on the executable path and authentication state (init receives 7 — the extra is CAP_KIND_PROC_READ with write rights for child signaling)
  4. Syscall: Every privileged syscall calls cap_check() against the calling process’s capability table
  5. Failure: Operations without required capabilities return ENOCAP (errno 130)

See Capability Model and Security Policy Engine for full details.

Syscall Interface

Aegis implements 100+ system calls via the SYSCALL/SYSRET fast-path mechanism. The entry point is in kernel/arch/x86_64/syscall_entry.asm; dispatch happens in kernel/syscall/syscall.c.

Syscalls are organized by category:

Category File Examples
I/O sys_io.c read, write, ioctl, poll, select
Memory sys_memory.c mmap, munmap, brk, mprotect
Process sys_process.c fork, wait, exit, getpid
Exec sys_exec.c execve
Identity sys_identity.c getuid, setuid, getgid
Capabilities sys_cap.c cap_get, cap_set
Time sys_time.c clock_gettime, nanosleep
Files sys_file.c open, close, stat, fstat
Directories sys_dir.c mkdir, rmdir, getdents
Metadata sys_meta.c chmod, chown, uname
Signals sys_signal.c kill, sigaction, sigreturn
Sockets sys_socket.c socket, bind, listen, connect, accept, sendto, recvfrom
Random sys_random.c getrandom
Disk sys_disk.c Disk management operations
Futex futex.c futex_wait, futex_wake

See Syscall Interface for the complete reference.

Virtual File System

The VFS provides a unified interface over 8 filesystem implementations:

Filesystem Type Description
ext2 On-disk Primary filesystem; read-write support with block caching
ramfs In-memory RAM-backed tmpfs for /tmp and runtime data
procfs Pseudo Process information (/proc)
initrd Boot Initial ramdisk (embedded blobs: login, shell, vigil)
memfd Anonymous Anonymous memory-backed files for IPC
pipe IPC Unidirectional byte stream between processes
console Device Kernel console (stdout)
pty Terminal Pseudo-terminal pairs for terminal emulators

Additional VFS components: kbd_vfs (keyboard device), blkdev (block device layer), gpt (GPT partition table parsing), fd_table (per-process file descriptor table).

See VFS Layer, ext2, and procfs for implementation details.

Network Stack

Aegis implements a full TCP/IP network stack:

┌──────────────────────────────────────┐
│         Socket API (socket.c)        │
│   socket · bind · listen · connect   │
│   accept · sendto · recvfrom · poll  │
├──────────────────────────────────────┤
│     UNIX Sockets (unix_socket.c)     │
│          epoll (epoll.c)             │
├──────────┬───────────┬───────────────┤
│   TCP    │    UDP    │     ICMP      │
│ (tcp.c)  │  (udp.c)  │   (icmp.c)    │
├──────────┴───────────┴───────────────┤
│            IP Layer (ip.c)           │
│              ARP (arp.c)             │
├──────────────────────────────────────┤
│         Ethernet (eth.c)             │
├──────────────────────────────────────┤
│        Network Device (netdev.c)     │
├──────────┬───────────────────────────┤
│virtio-net│       RTL8169             │
│(virtio_  │    (rtl8169.c)            │
│ net.c)   │                           │
└──────────┴───────────────────────────┘

The stack supports:

  • Full TCP state machine (connect, listen, accept, data transfer, graceful close)
  • UDP send/receive
  • ICMP echo (ping) for self-test and diagnostics
  • ARP resolution
  • UNIX domain sockets for local IPC
  • epoll for scalable I/O multiplexing
  • Two NIC drivers: virtio-net (QEMU) and RTL8169/RTL8168 (real hardware)

See Network Stack, TCP/IP, and Socket API for details.

Scheduler

Round-robin preemptive scheduler with:

  • Per-task kernel stacks allocated from KVA
  • Context switch via ctx_switch.asm (saves/restores all general-purpose registers + SSE state)
  • LAPIC timer-driven preemption
  • Wait queues for blocking I/O operations
  • SMP support: application processors started via INIT-SIPI-SIPI sequence

The idle task (task_idle) runs when no other task is runnable, executing HLT in a loop.

See Scheduler for the full design.

Process Management

  • ELF loader: Loads dynamically-linked ELF64 executables via proc_spawn and sys_exec
  • Fork: Full copy-on-write fork() creating a new process with duplicated address space and capability table
  • Exec: Replaces process image, sets up new stack with argc/argv/envp, maps the dynamic linker (ld-musl-x86_64.so.1)
  • Wait/Exit: Standard POSIX waitpid/exit semantics
  • Init process: PID 1 is always Vigil, spawned by proc_spawn_init() at the end of kernel initialization

See Processes & ELF for details.

Device Drivers

Driver File Hardware
NVMe nvme.c NVM Express block storage
xHCI xhci.c USB 3.0 host controller
USB HID usb_hid.c USB keyboard
USB Mouse usb_mouse.c USB mouse
virtio-net virtio_net.c QEMU virtio network adapter
RTL8169 rtl8169.c Realtek RTL8168/8169 Gigabit Ethernet
Framebuffer fb.c Linear framebuffer (VBE/UEFI GOP)
Ramdisk ramdisk.c RAM-backed block device (GRUB modules)

All PCIe devices are discovered via ECAM (Enhanced Configuration Access Mechanism) during pcie_init(). Drivers register themselves during the boot sequence and are matched against discovered devices.

See Drivers for the full driver architecture.

GUI Stack

Aegis includes a complete custom GUI stack – no X11, no Wayland. All rendering goes directly to the kernel framebuffer.

┌──────────────────────────────────────────────┐
│             Citadel (Desktop Shell)          │
│  Taskbar · Dock · Window decorations         │
│  Application launcher · Status indicators    │
├──────────────────────────────────────────────┤
│               Lumen (Compositor)             │
│  Window management · Compositing · Fade-in   │
│  Mouse cursor · Drag · Dock click handling   │
│  Direct framebuffer rendering (sys_fb_map)   │
├──────────────────────────────────────────────┤
│            Glyph (Widget Toolkit)            │
│  Text rendering (TTF) · Buttons · Text fields│
│  Layout primitives · Focus management        │
├──────────────────────────────────────────────┤
│            Bastion (Display Manager)         │
│  Graphical login greeter · Authentication    │
│  Session launch → Lumen + Citadel            │
└──────────────────────────────────────────────┘
  • Bastion: Display manager providing a graphical login greeter. After successful authentication (via libauth), spawns Lumen
  • Lumen: Compositor and display server. Manages windows, composites surfaces, handles mouse input with 1.5x speed multiplier, renders directly to the mapped framebuffer
  • Glyph: Widget toolkit library providing text rendering (TrueType), buttons, text input fields, layout primitives, and focus management
  • Citadel: Desktop shell library providing taskbar, dock (with app icons), window decorations, and application launching

See Lumen Compositor, Glyph Toolkit, and Citadel Desktop for details.

Userspace

Init System (Vigil)

Vigil is the PID 1 init system and service manager. It reads service definitions from /etc/vigil/, manages service lifecycles, handles dependencies, and provides the vigictl control interface.

See Vigil Init System for details.

Shells

  • shell (/bin/sh): Minimal statically-linked shell, embedded in the initrd. Available before the rootfs is mounted.
  • stsh (/bin/stsh): Secure shell (capability-aware). The primary interactive shell after boot.

Coreutils

Aegis provides 25+ coreutils: ls, cat, echo, pwd, uname, clear, true, false, wc, grep, sort, mkdir, touch, rm, cp, mv, whoami, ln, chmod, chown, readlink, shutdown, reboot.

See Shell & Coreutils for details.

Services

  • httpd: Built-in web server
  • dhcp: DHCP client for automatic network configuration
  • chronos: Time synchronization service
  • curl: HTTP client (BearSSL TLS)
  • rune: Text editor (Rust)
  • installer/gui-installer: System installers (text and graphical)

See Services for details.

Interrupt Architecture

External Interrupts                     Software Interrupts
┌──────────────┐                        ┌──────────────────┐
│ PIT (IRQ 0)  │──┐                     │ SYSCALL/SYSRET   │
│ KBD (IRQ 1)  │──┤                     │ (MSR-based,      │
│ COM1 (IRQ 4) │──┤   ┌──────────┐      │  no IDT entry)   │
│ Mouse(IRQ 12)│──┼──►│ 8259 PIC │      └──────────────────┘
│ ...          │──┘   │  (early) │
└──────────────┘      └────┬─────┘
                           │ remapped to vectors 0x20-0x2F
                           ▼
                      ┌─────────┐
                      │   IDT   │ 48+ gates
                      │ (idt.c) │
                      └────┬────┘
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
   ┌──────────┐      ┌─────────┐       ┌──────────┐
   │  LAPIC   │      │ IOAPIC  │       │Exceptions│
   │ (timer,  │      │ (IRQ    │       │ #PF, #GP │
   │  IPI)    │      │ routing)│       │ #DE, ... │
   └──────────┘      └─────────┘       └──────────┘

Early boot uses the 8259A PIC (remapped to vectors 0x20-0x2F). After ACPI parsing, the system transitions to LAPIC + IOAPIC for SMP-capable interrupt routing. The LAPIC timer provides per-CPU preemption.

See Interrupts & Exceptions for details.

Memory Layout

Virtual Address Space (canonical 48-bit):

0xFFFFFFFF80000000 ┌──────────────────────────┐
                   │     Kernel .text         │
                   │     Kernel .rodata       │
                   │     Kernel .data/.bss    │
                   │     KVA region           │
                   │     (task stacks, DMA,   │
                   │      device MMIO)        │
0xFFFF800000000000 ├──────────────────────────┤
                   │                          │
                   │   (non-canonical hole)   │
                   │                          │
0x0000800000000000 ├──────────────────────────┤
                   │                          │
                   │   User space             │
                   │   (per-process VMA)      │
                   │   Stack ↓   Heap ↑       │
                   │   mmap regions           │
                   │   ELF segments           │
                   │   Dynamic linker         │
                   │                          │
0x0000000000000000 └──────────────────────────┘

See Memory Management for the full design.

Build System

The build system is a single-Makefile GNU Make setup that cross-compiles the kernel with x86_64-elf-gcc, assembles with NASM, builds the Rust capability library with cargo +nightly, compiles userspace programs against musl libc, constructs an ext2 rootfs image, and packages everything into a GRUB-bootable ISO.

Key commands:

make          # Build kernel ELF
make iso      # Full bootable ISO
make run      # Boot in QEMU (text VGA)
make run-fb   # Boot in QEMU (framebuffer)
make test     # Run integration test suite

See Build System and Testing Framework for details.

Note: Aegis is v1 software and under active development. Contributions are welcome – file issues or propose changes at exec/aegis.

Documentation Map

Kernel

Security

Networking

GUI

Userspace

Build