# re-fa/os architecture

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

- Interactive diagram: https://gitdiagram.com/re-fa/os
- Repository: https://github.com/re-fa/os

## Overview

Milestone OS is a freestanding x86 kernel. Its documented user workflow is keyboard or serial input to the interactive shell, which dispatches commands to memory, timer, and VFS services and prints results. The runtime also initializes CPU/platform support, memory management, USB and storage drivers, and filesystems. The README describes an older 32-bit/PIC/PIT configuration, while the tree includes x86_64 and newer device modules; unsampled implementation details and their connections are therefore omitted unless documented or shown by the excerpts.

Main entry points: [`kernel/entry.c`](https://github.com/re-fa/os/blob/main/kernel/entry.c) (Kernel entry), [`shell/shell.c`](https://github.com/re-fa/os/blob/main/shell/shell.c) (Interactive shell), [`fs/vfs.c`](https://github.com/re-fa/os/blob/main/fs/vfs.c) (Virtual filesystem), [`drivers/storage/ahci/ahci.c`](https://github.com/re-fa/os/blob/main/drivers/storage/ahci/ahci.c) (AHCI driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Kernel startup"]
  node_entry["Kernel entry<br/>[entry.c]"]
  node_descriptors["Descriptor tables"]
  node_idt["IDT setup<br/>[idt.c]"]
end

subgraph group_platform["Platform drivers"]
  node_acpi["ACPI discovery<br/>[acpi.c]"]
  node_apic["APIC control<br/>[apic.c]"]
  node_mmio["MMIO mapping<br/>[mmio.c]"]
  node_timer["Timer service<br/>[timer.c]"]
  node_xhci["xHCI controller<br/>[xhci.c]"]
  node_usbkeyboard["USB HID keyboard<br/>[keyboard.c]"]
  node_ps2["PS/2 keyboard<br/>[keyboard.c]"]
end

subgraph group_memory["Memory management"]
  node_pmm["Physical memory<br/>[pmm.c]"]
  node_heap["Kernel heap<br/>[kheap.c]"]
end

subgraph group_storage["Storage and filesystems"]
  node_ahci["AHCI driver<br/>[ahci.c]"]
  node_block["Block device layer<br/>[block.c]"]
  node_gpt["GPT partitions<br/>[gpt.c]"]
  node_vfs["Virtual filesystem<br/>[vfs.c]"]
  node_ramfs[("RAM filesystem<br/>[ramfs.c]")]
  node_fat32["FAT32 filesystem<br/>[fat32.c]"]
end

subgraph group_interaction["Input and console"]
  node_keyboard["Keyboard input<br/>[keyboard.c]"]
  node_shell["Interactive shell<br/>[shell.c]"]
  node_vga["VGA console<br/>[vga.c]"]
  node_framebuffer["Framebuffer output<br/>[framebuffer.c]"]
  node_serial["Serial console<br/>[serial.c]"]
end

node_loader(("Multiboot loader"))
node_user(("User"))

node_loader -->|"loads kernel"| node_entry
node_entry -->|"initializes"| node_framebuffer
node_entry -->|"discovers"| node_acpi
node_entry -->|"initializes"| node_mmio
node_entry -->|"initializes"| node_apic
node_entry -.->|"configures"| node_idt
node_entry -->|"initializes"| node_timer
node_entry -->|"initializes"| node_pmm
node_entry -->|"initializes"| node_heap
node_entry -->|"polls"| node_xhci
node_entry -->|"polls"| node_ps2
node_entry -->|"initializes"| node_vfs
node_entry -.->|"initializes"| node_ahci
node_ahci -->|"maps registers"| node_mmio
node_ahci -->|"registers device"| node_block
node_gpt -.->|"reads sectors"| node_block
node_vfs -->|"uses backend"| node_ramfs
node_vfs -->|"uses backend"| node_fat32
node_fat32 -->|"reads and writes"| node_block
node_user -->|"enters commands"| node_shell
node_shell -->|"runs file commands"| node_vfs
node_shell -->|"queries memory"| node_pmm
node_shell -->|"queries uptime"| node_timer
node_shell -->|"prints output"| node_vga
node_shell -.->|"receives input"| node_keyboard
node_ps2 -.->|"submits key events"| node_keyboard
node_xhci -.->|"dispatches reports"| node_usbkeyboard
node_usbkeyboard -.->|"submits key events"| node_keyboard
node_entry -->|"initializes"| node_serial
node_user -->|"types commands"| node_serial
node_vga -->|"mirrors output"| node_serial

click node_entry "https://github.com/re-fa/os/blob/main/kernel/entry.c"
click node_descriptors "https://github.com/re-fa/os/blob/main/kernel/descriptor_tables.c"
click node_idt "https://github.com/re-fa/os/blob/main/arch/x86_64/idt.c"
click node_acpi "https://github.com/re-fa/os/blob/main/acpi/acpi.c"
click node_apic "https://github.com/re-fa/os/blob/main/drivers/apic/apic.c"
click node_mmio "https://github.com/re-fa/os/blob/main/arch/x86_64/mmio.c"
click node_timer "https://github.com/re-fa/os/blob/main/kernel/timer.c"
click node_xhci "https://github.com/re-fa/os/blob/main/drivers/usb/xhci/xhci.c"
click node_usbkeyboard "https://github.com/re-fa/os/blob/main/drivers/usb/hid/keyboard.c"
click node_ps2 "https://github.com/re-fa/os/blob/main/drivers/ps2/keyboard.c"
click node_keyboard "https://github.com/re-fa/os/blob/main/kernel/keyboard.c"
click node_pmm "https://github.com/re-fa/os/blob/main/mm/pmm.c"
click node_heap "https://github.com/re-fa/os/blob/main/mm/kheap.c"
click node_ahci "https://github.com/re-fa/os/blob/main/drivers/storage/ahci/ahci.c"
click node_block "https://github.com/re-fa/os/blob/main/drivers/storage/block.c"
click node_gpt "https://github.com/re-fa/os/blob/main/fs/gpt.c"
click node_vfs "https://github.com/re-fa/os/blob/main/fs/vfs.c"
click node_ramfs "https://github.com/re-fa/os/blob/main/fs/ramfs.c"
click node_fat32 "https://github.com/re-fa/os/blob/main/fs/fat32.c"
click node_shell "https://github.com/re-fa/os/blob/main/shell/shell.c"
click node_vga "https://github.com/re-fa/os/blob/main/kernel/vga.c"
click node_framebuffer "https://github.com/re-fa/os/blob/main/drivers/framebuffer/framebuffer.c"
click node_serial "https://github.com/re-fa/os/blob/main/drivers/serial/serial.c"

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_entry,node_descriptors,node_idt,node_user toneBlue
class node_acpi,node_apic,node_mmio,node_timer,node_xhci,node_usbkeyboard,node_ps2 toneAmber
class node_pmm,node_heap toneMint
class node_ahci,node_block,node_gpt,node_vfs,node_ramfs,node_fat32 toneRose
class node_keyboard,node_shell,node_vga,node_framebuffer,node_serial,node_loader toneIndigo
```

## Components

### Kernel startup

- [Kernel entry](https://github.com/re-fa/os/blob/main/kernel/entry.c): `kernel/entry.c`
- [Descriptor tables](https://github.com/re-fa/os/blob/main/kernel/descriptor_tables.c): `kernel/descriptor_tables.c`
- [IDT setup](https://github.com/re-fa/os/blob/main/arch/x86_64/idt.c): `arch/x86_64/idt.c`

### Platform drivers

- [ACPI discovery](https://github.com/re-fa/os/blob/main/acpi/acpi.c): `acpi/acpi.c`
- [APIC control](https://github.com/re-fa/os/blob/main/drivers/apic/apic.c): `drivers/apic/apic.c`
- [MMIO mapping](https://github.com/re-fa/os/blob/main/arch/x86_64/mmio.c): `arch/x86_64/mmio.c`
- [Timer service](https://github.com/re-fa/os/blob/main/kernel/timer.c): `kernel/timer.c`
- [xHCI controller](https://github.com/re-fa/os/blob/main/drivers/usb/xhci/xhci.c): `drivers/usb/xhci/xhci.c`
- [USB HID keyboard](https://github.com/re-fa/os/blob/main/drivers/usb/hid/keyboard.c): `drivers/usb/hid/keyboard.c`
- [PS/2 keyboard](https://github.com/re-fa/os/blob/main/drivers/ps2/keyboard.c): `drivers/ps2/keyboard.c`

### Memory management

- [Physical memory](https://github.com/re-fa/os/blob/main/mm/pmm.c): `mm/pmm.c`
- [Kernel heap](https://github.com/re-fa/os/blob/main/mm/kheap.c): `mm/kheap.c`

### Storage and filesystems

- [AHCI driver](https://github.com/re-fa/os/blob/main/drivers/storage/ahci/ahci.c): `drivers/storage/ahci/ahci.c`
- [Block device layer](https://github.com/re-fa/os/blob/main/drivers/storage/block.c): `drivers/storage/block.c`
- [GPT partitions](https://github.com/re-fa/os/blob/main/fs/gpt.c): `fs/gpt.c`
- [Virtual filesystem](https://github.com/re-fa/os/blob/main/fs/vfs.c): `fs/vfs.c`
- [RAM filesystem](https://github.com/re-fa/os/blob/main/fs/ramfs.c): `fs/ramfs.c`
- [FAT32 filesystem](https://github.com/re-fa/os/blob/main/fs/fat32.c): `fs/fat32.c`

### Input and console

- [Keyboard input](https://github.com/re-fa/os/blob/main/kernel/keyboard.c): `kernel/keyboard.c`
- [Interactive shell](https://github.com/re-fa/os/blob/main/shell/shell.c): `shell/shell.c`
- [VGA console](https://github.com/re-fa/os/blob/main/kernel/vga.c): `kernel/vga.c`
- [Framebuffer output](https://github.com/re-fa/os/blob/main/drivers/framebuffer/framebuffer.c): `drivers/framebuffer/framebuffer.c`
- [Serial console](https://github.com/re-fa/os/blob/main/drivers/serial/serial.c): `drivers/serial/serial.c`

### Other components

- **Multiboot loader**
- **User**

## Connections

- Multiboot loader → Kernel entry: loads kernel (evidence: `README.md`)
- Kernel entry → Framebuffer output: initializes (evidence: `kernel/entry.c`)
- Kernel entry → ACPI discovery: discovers (evidence: `kernel/entry.c`)
- Kernel entry → MMIO mapping: initializes (evidence: `kernel/entry.c`)
- Kernel entry → APIC control: initializes (evidence: `kernel/entry.c`)
- Kernel entry → IDT setup: configures
- Kernel entry → Timer service: initializes (evidence: `kernel/entry.c`)
- Kernel entry → Physical memory: initializes (evidence: `kernel/entry.c`)
- Kernel entry → Kernel heap: initializes (evidence: `kernel/entry.c`)
- Kernel entry → xHCI controller: polls (evidence: `kernel/entry.c`)
- Kernel entry → PS/2 keyboard: polls (evidence: `kernel/entry.c`)
- Kernel entry → Virtual filesystem: initializes (evidence: `kernel/entry.c`)
- Kernel entry → AHCI driver: initializes
- AHCI driver → MMIO mapping: maps registers (evidence: `drivers/storage/ahci/ahci.c`)
- AHCI driver → Block device layer: registers device (evidence: `drivers/storage/ahci/ahci.c`)
- GPT partitions → Block device layer: reads sectors
- Virtual filesystem → RAM filesystem: uses backend (evidence: `fs/vfs.c`)
- Virtual filesystem → FAT32 filesystem: uses backend (evidence: `fs/vfs.c`)
- FAT32 filesystem → Block device layer: reads and writes (evidence: `fs/fat32.c`)
- User → Interactive shell: enters commands (evidence: `README.md`)
- Interactive shell → Virtual filesystem: runs file commands (evidence: `shell/shell.c`)
- Interactive shell → Physical memory: queries memory (evidence: `shell/shell.c`)
- Interactive shell → Timer service: queries uptime (evidence: `shell/shell.c`)
- Interactive shell → VGA console: prints output (evidence: `shell/shell.c`)
- Interactive shell → Keyboard input: receives input
- PS/2 keyboard → Keyboard input: submits key events
- xHCI controller → USB HID keyboard: dispatches reports
- USB HID keyboard → Keyboard input: submits key events
- Kernel entry → Serial console: initializes (evidence: `kernel/entry.c`)
- User → Serial console: types commands (evidence: `README.md`)
- VGA console → Serial console: mirrors output (evidence: `README.md`)
