# mdgaziur/ferricoxide-os architecture

> Architecture diagram of the GitHub repository mdgaziur/ferricoxide-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mdgaziur/ferricoxide-os
- Repository: https://github.com/mdgaziur/ferricoxide-os

## Overview

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/kernel.rs`](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/kernel.rs) (Kernel entry), [`kernel/arch/x86_64/mod.rs`](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/mod.rs) (x86_64 arch), [`prekernel/prekernel.rs`](https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/prekernel.rs) (Prekernel core), [`prekernel/arch/x86/boot/boot.asm`](https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/arch/x86/boot/boot.asm) (Boot asm)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_prekernel["Prekernel"]
  node_node_bootloader["GRUB boot<br/>bootloader<br/>[grub.cfg]"]
  node_node_boot_asm["Boot asm<br/>[boot.asm]"]
  node_node_prekernel_entry(("Prekernel main<br/>rust entry<br/>[main.rs]"))
  node_node_prekernel_core["Prekernel core<br/>bootstrap runtime<br/>[prekernel.rs]"]
  node_node_prekernel_cfg["x86 target<br/>build target"]
  node_node_prekernel_linker["Prekernel ld<br/>linker script<br/>[linker.ld]"]
  node_node_prekernel_kprintf["Boot print<br/>console util<br/>[kprintf.rs]"]
  node_node_prekernel_kutils["Boot utils<br/>helpers<br/>[kutils.rs]"]
  node_node_prekernel_asset["Splash asset<br/>tga asset<br/>[FerricOxide.tga]"]
end

subgraph group_group_kernel["Kernel"]
  node_node_kernel_core(("Kernel entry<br/>kernel core<br/>[kernel.rs]"))
  node_node_kernel_arch["x86_64 arch<br/>platform layer<br/>[mod.rs]"]
  node_node_cpu["CPU setup<br/>cpu init<br/>[cpu.rs]"]
  node_node_gdt["GDT<br/>descriptor tables<br/>[gdt.rs]"]
  node_node_acpi["ACPI<br/>platform discovery<br/>[acpi.rs]"]
  node_node_interrupts["Interrupts<br/>irq stack<br/>[mod.rs]"]
  node_node_mm["Memory mgmt<br/>mm subsystem<br/>[mm.rs]"]
  node_node_display["Display<br/>framebuffer output<br/>[mod.rs]"]
  node_node_vfs["VFS<br/>filesystem layer<br/>[mod.rs]"]
  node_node_ramfs["Ramfs<br/>in-memory fs<br/>[mod.rs]"]
  node_node_process["Process<br/>task layer<br/>[mod.rs]"]
  node_node_kernel_dbg["Debug<br/>[mod.rs]"]
  node_node_kernel_kprintf["Kernel print<br/>console util<br/>[kprintf.rs]"]
  node_node_kernel_kutils["Kernel utils<br/>helpers<br/>[kutils.rs]"]
  node_node_ds["Data structs<br/>support library<br/>[ds.rs]"]
end

node_node_bootloader -->|"loads"| node_node_boot_asm
node_node_boot_asm -->|"enters"| node_node_prekernel_entry
node_node_prekernel_entry -->|"initializes"| node_node_prekernel_core
node_node_prekernel_core -->|"handoff"| node_node_kernel_core
node_node_prekernel_cfg -->|"targets"| node_node_boot_asm
node_node_prekernel_linker -->|"links"| node_node_boot_asm
node_node_prekernel_kprintf -->|"reports"| node_node_prekernel_core
node_node_prekernel_kutils -->|"supports"| node_node_prekernel_core
node_node_prekernel_asset -.->|"used by"| node_node_prekernel_core
node_node_kernel_core -->|"boots"| node_node_kernel_arch
node_node_kernel_arch -->|"contains"| node_node_cpu
node_node_kernel_arch -->|"contains"| node_node_gdt
node_node_kernel_arch -->|"contains"| node_node_acpi
node_node_kernel_arch -->|"contains"| node_node_interrupts
node_node_kernel_arch -->|"contains"| node_node_mm
node_node_acpi -->|"feeds"| node_node_interrupts
node_node_mm -->|"enables"| node_node_process
node_node_kernel_core -->|"uses"| node_node_display
node_node_kernel_core -->|"mounts"| node_node_vfs
node_node_vfs -->|"backed by"| node_node_ramfs
node_node_kernel_core -->|"starts"| node_node_process
node_node_kernel_core -->|"exposes"| node_node_kernel_dbg
node_node_kernel_kprintf -->|"logs"| node_node_kernel_core
node_node_kernel_kutils -->|"supports"| node_node_kernel_core
node_node_ds -->|"supports"| node_node_kernel_core

click node_node_bootloader "https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/arch/x86/boot/grub.cfg"
click node_node_boot_asm "https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/arch/x86/boot/boot.asm"
click node_node_prekernel_entry "https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/arch/x86/main.rs"
click node_node_prekernel_core "https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/prekernel.rs"
click node_node_prekernel_cfg "https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/arch/x86/i686-ferricoxide_os.json"
click node_node_prekernel_linker "https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/arch/x86/linker.ld"
click node_node_prekernel_kprintf "https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/kprintf.rs"
click node_node_prekernel_kutils "https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/kutils.rs"
click node_node_prekernel_asset "https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/assets/FerricOxide.tga"
click node_node_kernel_core "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/kernel.rs"
click node_node_kernel_arch "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/mod.rs"
click node_node_cpu "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/cpu.rs"
click node_node_gdt "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/gdt.rs"
click node_node_acpi "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/acpi.rs"
click node_node_interrupts "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/interrupts/mod.rs"
click node_node_mm "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/mm.rs"
click node_node_display "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/display/mod.rs"
click node_node_vfs "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/fs/vfs/mod.rs"
click node_node_ramfs "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/fs/ramfs/mod.rs"
click node_node_process "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/process/mod.rs"
click node_node_kernel_dbg "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/dbg/mod.rs"
click node_node_kernel_kprintf "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/kprintf.rs"
click node_node_kernel_kutils "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/kutils.rs"
click node_node_ds "https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/ds.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_bootloader,node_node_boot_asm,node_node_prekernel_entry,node_node_prekernel_core,node_node_prekernel_cfg,node_node_prekernel_linker,node_node_prekernel_kprintf,node_node_prekernel_kutils,node_node_prekernel_asset toneBlue
class node_node_kernel_core,node_node_kernel_arch,node_node_cpu,node_node_gdt,node_node_acpi,node_node_interrupts,node_node_mm,node_node_display,node_node_vfs,node_node_ramfs,node_node_process,node_node_kernel_dbg,node_node_kernel_kprintf,node_node_kernel_kutils,node_node_ds toneAmber
```

## Components

### Prekernel

32-bit boot stage and early handoff code.

- [GRUB boot](https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/arch/x86/boot/grub.cfg): bootloader · Loads the early stage via GRUB config and x86 boot entry. · `prekernel/arch/x86/boot/grub.cfg`
- [Boot asm](https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/arch/x86/boot/boot.asm): boot asm · Low-level x86 startup before Rust runs. · `prekernel/arch/x86/boot/boot.asm`
- [Prekernel main](https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/arch/x86/main.rs): rust entry · Early Rust entrypoint for the bootstrap environment. · `prekernel/arch/x86/main.rs`
- [Prekernel core](https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/prekernel.rs): bootstrap runtime · Coordinates early setup and the handoff into the main kernel. · `prekernel/prekernel.rs`
- [x86 target](https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/arch/x86/i686-ferricoxide_os.json): build target · 32-bit freestanding target specification for the early stage. · `prekernel/arch/x86/i686-ferricoxide_os.json`
- [Prekernel ld](https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/arch/x86/linker.ld): linker script · Link layout for the bootstrap binary. · `prekernel/arch/x86/linker.ld`
- [Boot print](https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/kprintf.rs): console util · Minimal printing and logging used before the kernel is up. · `prekernel/kprintf.rs`
- [Boot utils](https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/kutils.rs): helpers · Shared early-stage helper routines. · `prekernel/kutils.rs`
- [Splash asset](https://github.com/mdgaziur/ferricoxide-os/blob/main/prekernel/assets/FerricOxide.tga): tga asset · Early graphics asset used by the bootstrap stage. · `prekernel/assets/FerricOxide.tga`

### Kernel

64-bit kernel runtime and subsystems.

- [Kernel entry](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/kernel.rs): kernel core · Top-level kernel initialization and coordination point. · `kernel/kernel.rs`
- [x86_64 arch](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/mod.rs): platform layer · Low-level CPU, memory, interrupt, and platform bring-up. · `kernel/arch/x86_64/mod.rs`
- [CPU setup](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/cpu.rs): cpu init · Processor feature detection and CPU state setup. · `kernel/arch/x86_64/cpu.rs`
- [GDT](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/gdt.rs): descriptor tables · Segment descriptor table setup for x86_64. · `kernel/arch/x86_64/gdt.rs`
- [ACPI](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/acpi.rs): platform discovery · System discovery and topology-related platform tables. · `kernel/arch/x86_64/acpi.rs`
- [Interrupts](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/interrupts/mod.rs): irq stack · Interrupt-controller and timer support. · `kernel/arch/x86_64/interrupts/mod.rs`
- [Memory mgmt](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/arch/x86_64/mm.rs): mm subsystem · Physical frame allocation and virtual memory management. · `kernel/arch/x86_64/mm.rs`
- [Display](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/display/mod.rs): framebuffer output · Framebuffer and text rendering for kernel output. · `kernel/display/mod.rs`
- [VFS](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/fs/vfs/mod.rs): filesystem layer · Filesystem abstraction layer over concrete backing stores. · `kernel/fs/vfs/mod.rs`
- [Ramfs](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/fs/ramfs/mod.rs): in-memory fs · In-memory filesystem implementation. · `kernel/fs/ramfs/mod.rs`
- [Process](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/process/mod.rs): task layer · Execution-context and process management boundary. · `kernel/process/mod.rs`
- [Debug](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/dbg/mod.rs): debug layer · Kernel debugging helpers and interfaces. · `kernel/dbg/mod.rs`
- [Kernel print](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/kprintf.rs): console util · Kernel-side printing and logging support. · `kernel/kprintf.rs`
- [Kernel utils](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/kutils.rs): helpers · Shared kernel helper routines and low-level utilities. · `kernel/kutils.rs`
- [Data structs](https://github.com/mdgaziur/ferricoxide-os/blob/main/kernel/ds.rs): support library · Core shared data structures used across kernel subsystems. · `kernel/ds.rs`

## Connections

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