RustOS — x86_64 Bare-Metal Preemptive Microkernel: Master Index

A comprehensive navigation hub for RustOS—a bare-metal, 64-bit x86 multitasking microkernel engineered in Rust with zero standard library dependencies. Features Global Descriptor Table segmentation, Task State Segment stack isolation, dual-8259 PIC interrupt remapping, 4-level paging with physical memory offset translation, power-of-two slab heap allocation, preemptive SysV64 context switching, custom blocking sleep-locks, and an in-memory virtual filesystem with an interactive shell.


📂 File Directory

File Type Duration Primary Focus
intro Speech 1–2 mins Crisp elevator pitch on motivation, mental models learned, and full architectural scope without low-level code minutiae.
detailed Speech 4–5 mins End-to-end architectural blueprint touching all 6 subsystems with embedded breadcrumb hooks to topic deep dives.
topic_01_boot_gdt_and_tss Deep Dive 2–3 mins GDT table setup, Task State Segment structure, Interrupt Stack Table (IST 0), and hardware-enforced double fault isolation to prevent triple fault reboots.
topic_02_idt_pic_and_interrupt_handling Deep Dive 2–3 mins IDT exception gates, 8259 dual-PIC remapping to vectors 32–47, EOI signaling, and interrupt-disabled locking (without_interrupts) to eliminate VGA console deadlocks.
topic_03_paging_and_frame_allocator Deep Dive 2–3 mins 4-level paging hierarchy, CR3 register inspection, complete physical memory offset mapping ($V = \text{Offset} + P$), and BootInfoFrameAllocator physical RAM parsing.
topic_04_kernel_heap_and_fixed_size_allocator Deep Dive 2–3 mins 100 KiB heap mapping at 0x4444_4444_0000, comparison of Bump vs. Linked List vs. Fixed-Size Block allocators, power-of-two slab freelists (8B to 2048B), and fallback heap.
topic_05_preemptive_multitasking_and_mutex Deep Dive 2–3 mins Process Control Block (PCB), synthetic stack frames, naked assembly context switching (mov rsp, rax), round-robin scheduler queues, and custom blocking sleep-locks.
topic_06_in_memory_vfs_and_shell Deep Dive 2–3 mins PS/2 keyboard controller port 0x60, scancode state machine decoding, thread-safe input ring buffer, hierarchical in-memory VFS (Directory/File), and interactive shell REPL.
topic_07_synchronization_mutex_and_semaphore Deep Dive / Notes 3–4 mins Kernel synchronization layer (src/sync.rs), blocking Mutex<T> with atomic CAS and sleep queues, counting Semaphore with wait queues, RAII MutexGuard, and Spinlock comparison.
code.html (Source Code Browser) Interactive Tool Interactive 18 RustOS kernel source files, 146 symbol definitions, syntax highlighting, click-to-highlight, and quick-open navigation.

🏗️ Architecture Overview

graph TD
    subgraph Boot ["1. Bare-Metal Boot & Initialization"]
        BIOS[BIOS / UEFI Firmware] --> Bootloader[x86_64 Bootloader]
        Bootloader --> Entry["src/main.rs: entry_point!(kernel_main)"]
        Entry --> InitGDT["src/gdt.rs: init() - GDT & TSS (IST 0)"]
        Entry --> InitIDT["src/interrupts.rs: init_idt() - IDT & 8259 PIC"]
        Entry --> InitMem["src/memory.rs: init(phys_mem_offset) - 4-Level Paging"]
        Entry --> InitHeap["src/allocator.rs: init_heap() - 100 KiB Slab Allocator"]
    end

    subgraph Trap ["2. Hardware Traps & Concurrency Pipeline"]
        Timer[8253 PIT: Vector 32] --> ISR["interrupts.rs: timer_interrupt_handler (Naked Assembly)"]
        Keyboard[PS/2 Keyboard: Vector 33] --> KeyISR["interrupts.rs: keyboard_interrupt_handler"]
        KeyISR --> KeyBuf["keyboard.rs: INPUT_BUFFER (Ring Buffer)"]
        ISR --> PushRegs["Push 15 General-Purpose Registers"]
        PushRegs --> SchedCall["process.rs: timer_schedule(current_rsp)"]
        SchedCall --> SwitchRSP["mov rsp, next_task.rsp"]
        SwitchRSP --> PopRegs["Pop 15 General-Purpose Registers"]
        PopRegs --> EOI["Send EOI (0x20) & iretq"]
    end

    subgraph Runtime ["3. Tasks, Synchronization & Filesystem"]
        SchedCall --> QReady["Ready Queue (VecDeque)"]
        SchedCall --> QBlock["Blocked Queue (VecDeque)"]
        SchedCall --> QTerm["Terminated Queue (VecDeque)"]
        Tasks["Active Tasks: Shell, Clock, Counter, Idle"] --> Mutex["sync.rs: Mutex (Sleep/Wake queues)"]
        Tasks --> Shell["shell.rs: start_shell()"]
        Shell --> VFS["fs.rs: FileSystem (In-Memory Tree)"]
    end