How mobeen0119/forgeos works
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: main.c Kernel entry · paging.c Paging · task.c Tasks · Process Scheduler
Components 20
Boot
GRUB-based boot and image build path
- Boot path · Bootloader config and entry assembly that produce the kernel image/ISO
boot/boot.s - GRUB config · Boot menu and ISO boot wiring
boot/grub.cfg
Core kernel
CPU, interrupts, and entry sequencing
- Kernel entry · Top-level kernel startup and subsystem bring-up order
kernel/main.c - CPU traps · GDT, IDT, ISR stubs, interrupt dispatch, and CPU setup
kernel/CPU - TSS/syscall · TSS and syscall entry glue for ring transitions
kernel/TSS
Memory
Physical memory, paging, and allocation layers
- PMM · Physical frame management and base memory tracking
kernel/Memory/pmm.c - Allocators · Buddy, slab, heap, and allocation tracking utilities
kernel/Memory - Paging · Page tables, MMU glue, and page fault handling
kernel/Paging/paging.c - Panic path · Paging panic/reporting and invalid-memory escalation
kernel/Paging/Forge_Panic
Process
Tasks, scheduling, exec/fork, and syscall boundary
- Tasks · Task objects, lifecycle, and scheduler-visible state
kernel/Process/task.c - Scheduler · Ready queue, timer-driven scheduling, and context switching
kernel/Process - Fork/exec · Fork, exec, user-space setup, and initial stack construction
kernel/Process/exec.c - Process diag · Task visibility, quarantine, stack maps, and leak/liveness helpers
kernel/Process - PIT tick · Timer interrupt source for preemptive multitasking
Drivers/PIT/pit.c
I/O and shell
Devices, VFS, terminal, and user-facing command loop
- Devices · Keyboard, TTY, and low-level device plumbing
kernel/Dev - VFS/RAMFS · Virtual filesystem boundary and RAM-backed storage
kernel/VFS/vfs.c - Terminal · TTY, terminal, screen, and console rendering path
kernel/terminal.c - Kernel shell · Parser, builtins, identity, and memory info commands
kernel/Shell/shell.c
Userland
Thin user programs and syscall wrappers
- Syscall lib · User-space syscall wrappers for read, write, exit, and generic calls
User/lib/Syscall_U.c - User apps · Small user programs such as shell, cat, and exec tests
User/Programs/shell.c
Connections 28
- 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