# mobeen0119/forgeos architecture

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

- Interactive diagram: https://gitdiagram.com/mobeen0119/forgeos
- Repository: https://github.com/mobeen0119/forgeos

## Overview

1. ForgeOS is a 32-bit x86 hobby operating system split into three main layers: boot/runtime setup, the kernel, and a small userland. The boot path is GRUB-based, with `boot/boot.s` and `boot/grub.cfg` producing an ISO for QEMU. The kernel and user programs are linked separately, which is important because user processes are meant to run through syscalls and page boundaries rather than directly in kernel address space.

2. The kernel entrypoint is `kernel/main.c`, which brings up core subsystems in a fairly classic order: CPU/interrupt setup, memory management, paging, devices, VFS, process/task support, and finally the interactive shell. That sequencing matters because later subsystems depend on earlier ones—for example, process creation depends on heap/page allocation, and the shell depends on keyboard, TTY, and filesystem support.

3. CPU and interrupt handling live under `kernel/CPU`, `kernel/Paging`, `kernel/Syscall`, and `kernel/TSS`. These directories hold the x86-specific assembly/C glue for GDT, IDT, TSS, ISR stubs, syscall entry, and interrupt handlers. The architecture is strongly trap-driven: timer interrupts preempt tasks, fault handlers catch invalid memory access, and a dedicated syscall path transfers control from user mode into the kernel.

4. Time slicing is driven by the PIT driver in `Drivers/PIT` plus the process timer handler assembly in `kernel/Process/timer_handler.asm`. The PIT acts as the scheduler tick source, so preemptive multitasking is interrupt-based rather than cooperative. This makes the timer interrupt a key boundary between hardware timing and the process scheduler.

5. Memory management is layered. Physical memory management is in `kernel/Memory/pmm.c`, with higher-level allocators built on top: buddy allocation, slab allocation, kernel heap, and supporting trackers/freezing utilities. The README highlights a subtle allocator invariant: allocations must account for metadata headers, and buddy blocks must be carved from one aligned power-of-two region for correct free-list behavior. This is a central architectural constraint because process creation and kernel stacks depend on it.

6. Paging and virtual memory are separated from the allocators. `kernel/Paging/paging.c`, `mmu.s`, and the page fault code manage address translation and fault handling, while `kernel/Memory` provides the backing frames and heap objects. The `kernel/Paging/Forge_Panic` area suggests a panic/reporting path when paging invariants are violated. In diagram terms, virtual memory sits between processes and physical allocation, with page faults feeding back into the kernel fault handler.

7. Process management is a major subsystem under `kernel/Process`. It includes task objects, fork/exec, user-space setup, stack/context switching, and a set of process-accounting/debug modules like `StackMap`, `TaskLife`, `WhyAlive`, `OutLook`, `FDLeak`, and `Quarantine`. The README’s scheduler note is important: ForgeOS separates `context_switch(old_esp, new_esp)` from `trap_return`, so normal scheduling and first-entry/return-to-user use different primitives. That split is the core process boundary to capture in a diagram.

8. Process state is organized around two collections: `all_tasks`, which retains every task including zombies for inspection and `waitpid`, and `ready_queue`, which contains only runnable tasks. Exited tasks leave the ready queue immediately but remain in `all_tasks` until reaped. This means task lifecycle is not just “running vs not running”; there is a zombie/reaped dimension that affects process visibility and parent-child cleanup.

9. User/kernel transition is handled through `kernel/Syscall` and `User/lib`. User programs call thin syscall wrappers (`read`, `write`, `exit`, and a generic syscall interface), which trap into the kernel. `fork`, `exec`, and task creation depend on shared stack-frame conventions between the syscall path and the scheduler, which is why the README emphasizes a single helper for building initial stacks. The `sys_exec` note indicates exec replaces the image immediately in memory but completes through the normal return path, so the actual mode switch happens on the next schedule point.

10. File and device I/O are unified through the VFS layer in `kernel/VFS`, with a RAM-backed filesystem implementation (`RAMFS.c`) and interfaces declared in `Include/vfs.h` and `Include/ramfs.h`. This is the filesystem boundary the shell and user programs consume. Because the filesystem is RAM-backed, persistence is not the focus; the architecture is centered on in-memory objects and kernel-mediated file descriptors.

11. Human I/O is routed through drivers and terminal layers. `Drivers/keyboard.c`, `Drivers/tty.c`, `kernel/terminal.c`, and `kernel/screen.c` form the input/output path from hardware events to text display. The interactive shell spans both kernel and userland: there is a kernel shell/parser/builtins subsystem and also user programs like `shell.c`, `cat.c`, and `exectest.c`. In an architecture diagram, this is the main user-facing loop: keyboard input → tty/terminal → shell parser → builtins or exec → output back to screen.

12. Shared support code is in `Lib` and `kernel/io.c`, providing string, math, and formatted-print utilities that are reused across kernel and userland code. Build tooling is intentionally simple: a Makefile and shell script produce the kernel ELF and bootable ISO. The repository also includes `kernel/selftest.c` and `TODO.md`, indicating some internal validation and ongoing kernel development rather than a finished product.

Main entry points: [`kernel/main.c`](https://github.com/mobeen0119/forgeos/blob/main/kernel/main.c) (Kernel entry), [`kernel/Paging/paging.c`](https://github.com/mobeen0119/forgeos/blob/main/kernel/Paging/paging.c) (Paging), [`kernel/Process/task.c`](https://github.com/mobeen0119/forgeos/blob/main/kernel/Process/task.c) (Tasks), [`kernel/Process`](https://github.com/mobeen0119/forgeos/tree/main/kernel/Process) (Scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_boot["Boot"]
  node_boot_boot["Boot path<br/>GRUB boot<br/>[boot.s]"]
  node_boot_grub["GRUB config<br/>boot config<br/>[grub.cfg]"]
end

subgraph group_grp_core["Core kernel"]
  node_kernel_main["Kernel entry<br/>init sequence<br/>[main.c]"]
  node_cpu_int["CPU traps<br/>x86 irq/idt"]
  node_tss_syscall["TSS/syscall<br/>privilege switch"]
end

subgraph group_grp_mem["Memory"]
  node_mem_pmm[("PMM<br/>physical memory<br/>[pmm.c]")]
  node_mem_alloc["Allocators<br/>heap/slab/buddy"]
  node_paging_vm["Paging<br/>virtual memory<br/>[paging.c]"]
  node_panic_fault{{"Panic path<br/>fault report"}}
end

subgraph group_grp_proc["Process"]
  node_proc_task["Tasks<br/>task model<br/>[task.c]"]
  node_proc_sched["Scheduler<br/>preemptive tick"]
  node_proc_forkexec["Fork/exec<br/>process creation<br/>[exec.c]"]
  node_proc_diag["Process diag<br/>lifecycle tools"]
  node_pit_timer(("PIT tick<br/>hardware timer<br/>[pit.c]"))
end

subgraph group_grp_io["I/O and shell"]
  node_dev_io["Devices<br/>drivers"]
  node_vfs_fs["VFS/RAMFS<br/>filesystem<br/>[vfs.c]"]
  node_term_screen["Terminal<br/>text I/O<br/>[terminal.c]"]
  node_k_shell["Kernel shell<br/>command loop<br/>[shell.c]"]
end

subgraph group_grp_user["Userland"]
  node_u_lib["Syscall lib<br/>user wrappers<br/>[Syscall_U.c]"]
  node_u_apps["User apps<br/>programs<br/>[shell.c]"]
end

node_boot_boot -->|"boot image"| node_boot_grub
node_boot_grub -->|"load kernel"| node_kernel_main
node_kernel_main -->|"init traps"| node_cpu_int
node_kernel_main -->|"init memory"| node_mem_pmm
node_kernel_main -->|"enable paging"| node_paging_vm
node_kernel_main -->|"init devices"| node_dev_io
node_kernel_main -->|"mount fs"| node_vfs_fs
node_kernel_main -->|"start tasks"| node_proc_task
node_kernel_main -->|"launch shell"| node_k_shell
node_cpu_int -->|"ring transition"| node_tss_syscall
node_pit_timer -->|"tick"| node_proc_sched
node_proc_sched -->|"run queue"| node_proc_task
node_proc_sched -->|"dispatch"| node_proc_forkexec
node_mem_pmm -->|"frames"| node_mem_alloc
node_mem_alloc -->|"backing store"| node_paging_vm
node_paging_vm -->|"fault"| node_panic_fault
node_paging_vm -->|"user image"| node_proc_forkexec
node_proc_forkexec -->|"enter user"| node_u_lib
node_u_lib -->|"syscall"| node_tss_syscall
node_tss_syscall -->|"handle traps"| node_cpu_int
node_dev_io -->|"text i/o"| node_term_screen
node_term_screen -->|"console"| node_k_shell
node_k_shell -->|"builtins/fs"| node_vfs_fs
node_k_shell -->|"exec apps"| node_proc_forkexec
node_u_apps -->|"syscalls"| node_u_lib
node_u_apps -->|"file i/o"| node_vfs_fs
node_proc_task -.->|"inspect"| node_proc_diag
node_proc_task -->|"states"| node_proc_sched

click node_boot_boot "https://github.com/mobeen0119/forgeos/blob/main/boot/boot.s"
click node_boot_grub "https://github.com/mobeen0119/forgeos/blob/main/boot/grub.cfg"
click node_kernel_main "https://github.com/mobeen0119/forgeos/blob/main/kernel/main.c"
click node_cpu_int "https://github.com/mobeen0119/forgeos/tree/main/kernel/CPU"
click node_tss_syscall "https://github.com/mobeen0119/forgeos/tree/main/kernel/TSS"
click node_mem_pmm "https://github.com/mobeen0119/forgeos/blob/main/kernel/Memory/pmm.c"
click node_mem_alloc "https://github.com/mobeen0119/forgeos/tree/main/kernel/Memory"
click node_paging_vm "https://github.com/mobeen0119/forgeos/blob/main/kernel/Paging/paging.c"
click node_panic_fault "https://github.com/mobeen0119/forgeos/tree/main/kernel/Paging/Forge_Panic"
click node_proc_task "https://github.com/mobeen0119/forgeos/blob/main/kernel/Process/task.c"
click node_proc_sched "https://github.com/mobeen0119/forgeos/tree/main/kernel/Process"
click node_proc_forkexec "https://github.com/mobeen0119/forgeos/blob/main/kernel/Process/exec.c"
click node_proc_diag "https://github.com/mobeen0119/forgeos/tree/main/kernel/Process"
click node_pit_timer "https://github.com/mobeen0119/forgeos/blob/main/Drivers/PIT/pit.c"
click node_dev_io "https://github.com/mobeen0119/forgeos/tree/main/kernel/Dev"
click node_vfs_fs "https://github.com/mobeen0119/forgeos/blob/main/kernel/VFS/vfs.c"
click node_term_screen "https://github.com/mobeen0119/forgeos/blob/main/kernel/terminal.c"
click node_k_shell "https://github.com/mobeen0119/forgeos/blob/main/kernel/Shell/shell.c"
click node_u_lib "https://github.com/mobeen0119/forgeos/blob/main/User/lib/Syscall_U.c"
click node_u_apps "https://github.com/mobeen0119/forgeos/blob/main/User/Programs/shell.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_boot_boot,node_boot_grub toneBlue
class node_kernel_main,node_cpu_int,node_tss_syscall toneAmber
class node_mem_pmm,node_mem_alloc,node_paging_vm,node_panic_fault toneMint
class node_proc_task,node_proc_sched,node_proc_forkexec,node_proc_diag,node_pit_timer toneRose
class node_dev_io,node_vfs_fs,node_term_screen,node_k_shell toneIndigo
class node_u_lib,node_u_apps toneTeal
```

## Components

### Boot

GRUB-based boot and image build path

- [Boot path](https://github.com/mobeen0119/forgeos/blob/main/boot/boot.s): GRUB boot · Bootloader config and entry assembly that produce the kernel image/ISO · `boot/boot.s`
- [GRUB config](https://github.com/mobeen0119/forgeos/blob/main/boot/grub.cfg): boot config · Boot menu and ISO boot wiring · `boot/grub.cfg`

### Core kernel

CPU, interrupts, and entry sequencing

- [Kernel entry](https://github.com/mobeen0119/forgeos/blob/main/kernel/main.c): init sequence · Top-level kernel startup and subsystem bring-up order · `kernel/main.c`
- [CPU traps](https://github.com/mobeen0119/forgeos/tree/main/kernel/CPU): x86 irq/idt · GDT, IDT, ISR stubs, interrupt dispatch, and CPU setup · `kernel/CPU`
- [TSS/syscall](https://github.com/mobeen0119/forgeos/tree/main/kernel/TSS): privilege switch · TSS and syscall entry glue for ring transitions · `kernel/TSS`

### Memory

Physical memory, paging, and allocation layers

- [PMM](https://github.com/mobeen0119/forgeos/blob/main/kernel/Memory/pmm.c): physical memory · Physical frame management and base memory tracking · `kernel/Memory/pmm.c`
- [Allocators](https://github.com/mobeen0119/forgeos/tree/main/kernel/Memory): heap/slab/buddy · Buddy, slab, heap, and allocation tracking utilities · `kernel/Memory`
- [Paging](https://github.com/mobeen0119/forgeos/blob/main/kernel/Paging/paging.c): virtual memory · Page tables, MMU glue, and page fault handling · `kernel/Paging/paging.c`
- [Panic path](https://github.com/mobeen0119/forgeos/tree/main/kernel/Paging/Forge_Panic): fault report · Paging panic/reporting and invalid-memory escalation · `kernel/Paging/Forge_Panic`

### Process

Tasks, scheduling, exec/fork, and syscall boundary

- [Tasks](https://github.com/mobeen0119/forgeos/blob/main/kernel/Process/task.c): task model · Task objects, lifecycle, and scheduler-visible state · `kernel/Process/task.c`
- [Scheduler](https://github.com/mobeen0119/forgeos/tree/main/kernel/Process): preemptive tick · Ready queue, timer-driven scheduling, and context switching · `kernel/Process`
- [Fork/exec](https://github.com/mobeen0119/forgeos/blob/main/kernel/Process/exec.c): process creation · Fork, exec, user-space setup, and initial stack construction · `kernel/Process/exec.c`
- [Process diag](https://github.com/mobeen0119/forgeos/tree/main/kernel/Process): lifecycle tools · Task visibility, quarantine, stack maps, and leak/liveness helpers · `kernel/Process`
- [PIT tick](https://github.com/mobeen0119/forgeos/blob/main/Drivers/PIT/pit.c): hardware timer · Timer interrupt source for preemptive multitasking · `Drivers/PIT/pit.c`

### I/O and shell

Devices, VFS, terminal, and user-facing command loop

- [Devices](https://github.com/mobeen0119/forgeos/tree/main/kernel/Dev): drivers · Keyboard, TTY, and low-level device plumbing · `kernel/Dev`
- [VFS/RAMFS](https://github.com/mobeen0119/forgeos/blob/main/kernel/VFS/vfs.c): filesystem · Virtual filesystem boundary and RAM-backed storage · `kernel/VFS/vfs.c`
- [Terminal](https://github.com/mobeen0119/forgeos/blob/main/kernel/terminal.c): text I/O · TTY, terminal, screen, and console rendering path · `kernel/terminal.c`
- [Kernel shell](https://github.com/mobeen0119/forgeos/blob/main/kernel/Shell/shell.c): command loop · Parser, builtins, identity, and memory info commands · `kernel/Shell/shell.c`

### Userland

Thin user programs and syscall wrappers

- [Syscall lib](https://github.com/mobeen0119/forgeos/blob/main/User/lib/Syscall_U.c): user wrappers · User-space syscall wrappers for read, write, exit, and generic calls · `User/lib/Syscall_U.c`
- [User apps](https://github.com/mobeen0119/forgeos/blob/main/User/Programs/shell.c): programs · Small user programs such as shell, cat, and exec tests · `User/Programs/shell.c`

## Connections

- Boot path → GRUB config: boot image · GRUB config and boot assembly combine into the bootable image
- GRUB config → Kernel entry: load kernel · Boot flow transfers control into the kernel entrypoint
- Kernel entry → CPU traps: init traps · Kernel startup initializes CPU and interrupt state first
- Kernel entry → PMM: init memory · Physical memory comes online before higher-level allocation
- Kernel entry → Paging: enable paging · Virtual memory and page tables are initialized during bring-up
- Kernel entry → Devices: init devices · Keyboard, tty, and other device support are started
- Kernel entry → VFS/RAMFS: mount fs · VFS becomes available for shell and user programs
- Kernel entry → Tasks: start tasks · Task/process infrastructure is initialized after memory and paging
- Kernel entry → Kernel shell: launch shell · Interactive shell starts near the end of kernel init
- CPU traps → TSS/syscall: ring transition · Interrupt and privilege infrastructure feeds syscall entry
- PIT tick → Scheduler: tick · Timer interrupts drive preemptive scheduling
- Scheduler → Tasks: run queue · Scheduler operates on task state and ready queues
- Scheduler → Fork/exec: dispatch · Scheduling hands off into user task setup and returns
- PMM → Allocators: frames · Allocator layers build on physical page/frame management
- Allocators → Paging: backing store · Paging relies on allocators for frames and kernel heap objects
- Paging → Panic path: fault · Paging errors escalate into panic/reporting paths
- Paging → Fork/exec: user image · Process creation depends on page mappings and address-space setup
- Fork/exec → Syscall lib: enter user · Fork/exec paths prepare the user-mode calling convention
- Syscall lib → TSS/syscall: syscall · User wrappers trap into kernel syscall entry
- TSS/syscall → CPU traps: handle traps · Syscall and interrupt entry are serviced by the CPU trap machinery
- Devices → Terminal: text i/o · Keyboard and tty events are rendered through terminal/screen layers
- Terminal → Kernel shell: console · Interactive shell consumes terminal input and produces console output
- Kernel shell → VFS/RAMFS: builtins/fs · Shell commands interact with files and filesystem state
- Kernel shell → Fork/exec: exec apps · Shell can launch user programs through exec
- User apps → Syscall lib: syscalls · User programs rely on thin syscall wrappers
- User apps → VFS/RAMFS: file i/o · Programs read and write through the VFS boundary
- Tasks → Process diag: inspect · Lifecycle and accounting helpers observe task state
- Tasks → Scheduler: states · Runnable and zombie task state feeds scheduling and reaping
