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.
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