How mdgaziur/ferricoxide-os works
1. Overall shape
- The repository is split into two Rust crates: prekernel and kernel.
- That strongly suggests a two-stage OS boot architecture: an early bootstrap environment and a main kernel proper.
2. Boot and handoff boundary
- prekernel/arch/x86/boot/boot.asm, grub.cfg, and linker.ld show a classic x86 boot path driven by GRUB and assembly startup code.
- prekernel/arch/x86/main.rs is the Rust entrypoint for the early stage.
- The prekernel likely prepares minimal machine state and then transfers control to the main kernel.
3. Target architecture split
- prekernel targets 32-bit x86 (i686-ferricoxide_os.json).
- kernel targets x86_64 (x86_64-ferricoxide_os.json).
- This implies the project bridges from a 32-bit boot environment into a 64-bit kernel runtime.
4. Architectural subsystems in the kernel
- kernel/arch/x86_64/ contains the low-level platform code: CPU setup, GDT, ACPI, APIC, I/O, paging, frame allocation, and interrupts.
- This is the hardware boundary layer for the kernel; most higher-level modules depend on it.
5. CPU, descriptor tables, and interrupts
- cpu.rs, cpu/cpuid.rs, and gdt.rs cover processor feature detection and segmentation setup.
- interrupts/ contains APIC, IOAPIC, and PIT timer support, indicating the kernel manages both modern local/inter-processor interrupt controllers and a legacy timer source.
6. Memory management
- mm/frame.rs and mm/paging.rs with paging/flags.rs form the kernel’s physical and virtual memory management layer.
- The architecture suggests a clean split between frame allocation and page-table manipulation.
7. Hardware discovery and platform init
- acpi.rs and acpi/apic.rs indicate ACPI is used to discover system topology and interrupt-controller information.
- This is typically part of early kernel init, before higher-level scheduling or device services come online.
8. Display and console output
- display/framebuffer.rs and display/text_renderer.rs provide a framebuffer-based output path.
- kprintf.rs exists in both crates, so early boot and kernel code both have a lightweight logging/printing mechanism.
- kernel/dbg/ suggests a dedicated debugging interface or helpers layered on top of console output.
9. Storage and filesystem abstraction
- fs/vfs/ and fs/ramfs/ show a virtual filesystem layered over an in-memory RAM filesystem.
- That indicates the kernel has an internal filesystem boundary where higher-level code talks to VFS rather than a specific backing store.
10. Process layer
- process/mod.rs exists as a distinct subsystem, implying process/task management is separated from core hardware and storage code.
- Given the rest of the tree, this is likely where execution contexts and scheduling-related state will live, even if the implementation is still minimal.
11. Shared utilities and data structures
- ds.rs and kutils.rs in the kernel, plus kutils.rs in the prekernel, suggest shared low-level helpers and custom data structures.
- These are likely support code used across hardware, memory, and filesystem subsystems.
12. Assets and early graphics
- prekernel/assets/FerricOxide.tga indicates the early stage can load or use graphical assets, probably for splash/branding or framebuffer testing.
- That points to the prekernel doing more than pure text-mode bootstrapping.
13. Build and toolchain boundaries
- The repo uses Rust Cargo manifests per crate, a pinned rust-toolchain.toml, and per-arch linker scripts/target JSON files.
- Those files are important architectural markers: they define a freestanding OS build, not a normal hosted application build.
14. Key data flow for an architecture diagram
- Bootloader/GRUB loads the prekernel stage.
- The prekernel sets up the earliest runtime context and hands off to the x86_64 kernel.
- The kernel then initializes CPU state, memory, interrupts, and platform discovery.
- Once the low-level environment is ready, it can expose framebuffer output, VFS/ramfs, debugging, and process management.
Main entry points: kernel.rs Kernel entry · mod.rs x86_64 arch · prekernel.rs Prekernel core · boot.asm Boot asm
Components 24
Prekernel
32-bit boot stage and early handoff code.
- GRUB boot · Loads the early stage via GRUB config and x86 boot entry.
prekernel/arch/x86/boot/grub.cfg - Boot asm · Low-level x86 startup before Rust runs.
prekernel/arch/x86/boot/boot.asm - Prekernel main · Early Rust entrypoint for the bootstrap environment.
prekernel/arch/x86/main.rs - Prekernel core · Coordinates early setup and the handoff into the main kernel.
prekernel/prekernel.rs - x86 target · 32-bit freestanding target specification for the early stage.
prekernel/arch/x86/i686-ferricoxide_os.json - Prekernel ld · Link layout for the bootstrap binary.
prekernel/arch/x86/linker.ld - Boot print · Minimal printing and logging used before the kernel is up.
prekernel/kprintf.rs - Boot utils · Shared early-stage helper routines.
prekernel/kutils.rs - Splash asset · Early graphics asset used by the bootstrap stage.
prekernel/assets/FerricOxide.tga
Kernel
64-bit kernel runtime and subsystems.
- Kernel entry · Top-level kernel initialization and coordination point.
kernel/kernel.rs - x86_64 arch · Low-level CPU, memory, interrupt, and platform bring-up.
kernel/arch/x86_64/mod.rs - CPU setup · Processor feature detection and CPU state setup.
kernel/arch/x86_64/cpu.rs - GDT · Segment descriptor table setup for x86_64.
kernel/arch/x86_64/gdt.rs - ACPI · System discovery and topology-related platform tables.
kernel/arch/x86_64/acpi.rs - Interrupts · Interrupt-controller and timer support.
kernel/arch/x86_64/interrupts/mod.rs - Memory mgmt · Physical frame allocation and virtual memory management.
kernel/arch/x86_64/mm.rs - Display · Framebuffer and text rendering for kernel output.
kernel/display/mod.rs - VFS · Filesystem abstraction layer over concrete backing stores.
kernel/fs/vfs/mod.rs - Ramfs · In-memory filesystem implementation.
kernel/fs/ramfs/mod.rs - Process · Execution-context and process management boundary.
kernel/process/mod.rs - Debug · Kernel debugging helpers and interfaces.
kernel/dbg/mod.rs - Kernel print · Kernel-side printing and logging support.
kernel/kprintf.rs - Kernel utils · Shared kernel helper routines and low-level utilities.
kernel/kutils.rs - Data structs · Core shared data structures used across kernel subsystems.
kernel/ds.rs
Connections 25
- GRUB boot → Boot asm: loads · GRUB starts the x86 bootstrap path.
- Boot asm → Prekernel main: enters · Assembly startup transfers control into Rust.
- Prekernel main → Prekernel core: initializes · Early entry delegates to the bootstrap coordinator.
- Prekernel core → Kernel entry: handoff · Bootstrap stage transfers execution into the main kernel.
- x86 target → Boot asm: targets · Build target and boot code define the freestanding early binary.
- Prekernel ld → Boot asm: links · Linker script shapes the bootstrap image.
- Boot print → Prekernel core: reports · Early logging supports bootstrap progress and diagnostics.
- Boot utils → Prekernel core: supports · Utility code used by the early runtime.
- Splash asset → Prekernel core: used by · Bootstrap stage can load or render the asset.
- Kernel entry → x86_64 arch: boots · Main kernel starts platform bring-up through the arch layer.
- x86_64 arch → CPU setup: contains · Architecture layer sets up processor features and state.
- x86_64 arch → GDT: contains · Descriptor table setup is part of low-level bring-up.
- x86_64 arch → ACPI: contains · ACPI discovery lives in the platform layer.
- x86_64 arch → Interrupts: contains · Interrupt controllers and timers are managed here.
- x86_64 arch → Memory mgmt: contains · Memory management primitives are part of platform setup.
- ACPI → Interrupts: feeds · ACPI discovery informs interrupt-controller configuration.
- Memory mgmt → Process: enables · Process management depends on memory primitives.
- Kernel entry → Display: uses · Kernel output is routed through framebuffer/text rendering.
- Kernel entry → VFS: mounts · Kernel exposes filesystem services through VFS.
- VFS → Ramfs: backed by · RAM filesystem provides a concrete in-memory store.
- Kernel entry → Process: starts · Process layer is initialized after core platform bring-up.
- Kernel entry → Debug: exposes · Debugging interfaces sit alongside core kernel services.
- Kernel print → Kernel entry: logs · Kernel-side printing supports core diagnostics.
- Kernel utils → Kernel entry: supports · Shared helpers are used across the kernel.
- Data structs → Kernel entry: supports · Shared data structures underpin several kernel subsystems.