# iyush/cos architecture

> Architecture diagram of the GitHub repository iyush/cos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iyush/cos
- Repository: https://github.com/iyush/cos

## Overview

##### Project type and purpose
- This is a tiny x86_64 monolithic operating system written in C.
- It uses the Limine bootloader, implements basic physical memory management, interrupt handling, ELF loading, preemptive scheduling, and syscalls.
- It ships with a minimal “hello-world” userland binary.

##### File structure
- Top-level:
- limine/ + limine.cfg – the standalone bootloader.
- kernel/ – all kernel sources, entry code, linker script, GDB init, subsystems.
- userland/ – small C runtime (crt0.asm) and simple “hello-world” app.
- build.sh, run.sh, debug.sh – build and execution scripts.
- .bochsrc, shell.nix – emulator and environment configs.
- kernel/src: groups by functionality (boot/init, GDT/IDT, PIC, PMM, scheduler, syscall, ELF loader, VMM stub, tests).

##### Key README insights
- Purpose: minimal lines of code to achieve interrupts, memory allocation, ELF loading, scheduling, syscalls.
- Build flow: nix-shell → make limine → build OS & userland.
- Run/debug via QEMU or Bochs with forwarded stdout.

##### Main components
a. Hardware layer
- CPU, physical RAM, chipset, chipset’s PIC/APIC.
- BIOS/UEFI invoking bootloader.
b. Bootloader (Limine)
- limine.cfg → loads kernel image & passes control.
c. Kernel space
- Early init (assembly entry, GDT, IDT, PIC remap).
- Memory manager (physical allocator “pmm.c”).
- ELF loader (“elf.c”)
- Interrupt & exception handlers.
- Syscall interface (syscall.asm/c).
- Scheduler (preemptive multitasking).
- I/O layer (kio.c, io.c).
- VMM stub (vmm.c – placeholder).
d. Userland
- crt0.asm → sets up stack/args, jumps to main.
- hello-world/main.c → invokes syscalls.
e. Host integration
- QEMU/Bochs emulator (controlled by run.sh).
- Logging piped to host stdout.

##### Relationships & interactions
- BIOS/UEFI → Limine → kernel entry
- Kernel init: GDT/IDT → enable interrupts → scheduler timer → context switch tasks
- Userland tasks loaded via ELF loader → scheduled by kernel → make syscalls → handled by syscall.c
- Kernel memory requests use PMM → updates physical free list
- Interrupts (timer) drive preemption → scheduler picks next task
- Kernel logging calls go through emulator’s console → host stdout

##### Architectural patterns & principles
- Monolithic kernel: all core services in one address space.
- Layered initialization: assembly entry → hardware setup → memory → interrupts → higher services.
- Modular C code per subsystem.
- Clear separation: bootloader vs. kernel vs. userland.

##### Detail
- Every essential kernel subsystem as its own block.
- External dependencies: Limine build, nix environment, emulator.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Hardware
    subgraph "Hardware" 
        style Hardware fill:#dddddd,stroke:#888888
        BIOS_UEFI["BIOS/UEFI"]:::hardware
        CPU["CPU"]:::hardware
        RAM["Physical RAM"]:::hardware
        PIC["Chipset PIC/APIC"]:::hardware
    end

    %% Layer 2: Bootloader
    subgraph "Bootloader (Limine)" 
        style Bootloader fill:#add8e6,stroke:#4682b4
        LimineDir["Limine Directory"]:::bootloader
        LimineCFG["limine.cfg"]:::bootloader
    end

    %% Layer 3: Kernel Subsystems
    subgraph "Kernel Subsystems" 
        style Kernel fill:#90ee90,stroke:#2e8b57

        Init["Init & Entry (entry.c, gdt.c, idt.c/asm, pic.c/h)"]:::kernel
        PMM["Memory Manager (pmm.c)"]:::kernel
        ELFLoader["ELF Loader (elf.c/h)"]:::kernel
        Interrupts["Interrupt & Exception Handler"]:::kernel
        Syscall["Syscall Interface (syscall.asm/c)"]:::kernel
        Scheduler["Scheduler (scheduler.c/h, task.c)"]:::kernel
        IO["I/O Layer (io.c, kio.c/h)"]:::kernel
        VMM["VMM Stub (vmm.c)"]:::kernel
        Utils["Kern Utils (defs.c, assert.h, cpu.h, kstring.c/h, stdint.h)"]:::kernel
        Tests["Kernel Tests (test_kstring.c)"]:::kernel
    end

    %% Layer 4: Userland
    subgraph "Userland" 
        style Userland fill:#ffa500,stroke:#cc8400
        CRT0["C Runtime Startup (crt0.asm)"]:::userland
        Hello["Hello-World (main.c)"]:::userland
    end

    %% Layer 5: Emulator/Host
    subgraph "Emulator & Host" 
        style Host fill:#dddddd,stroke:#888888
        QEMU["QEMU/Bochs"]:::host
        RunScript["run.sh"]:::host
        BuildScript["build.sh"]:::host
        DebugScript["debug.sh"]:::host
        BochsCfg[".bochsrc"]:::host
        NixEnv["shell.nix"]:::host
        HostStdout["Host Stdout"]:::host
    end

    %% Connections
    BIOS_UEFI -->|"boot" | LimineDir
    LimineCFG -->|"config" | LimineDir
    LimineDir -->|"load kernel image"| Init

    Init -->|"setup memory"| PMM
    Init -->|"setup interrupts"| Interrupts
    Init -->|"initialize scheduler timer"| Scheduler
    PMM -->|"alloc pages"| ELFLoader
    ELFLoader -->|"load user tasks"| Scheduler
    Scheduler -->|"context switch"| Hello
    Hello -->|"sys_write"| Syscall
    Syscall -->|"handle syscall"| IO
    Interrupts -->|"timer interrupt"| Scheduler

    IO -->|"kernel log"| QEMU
    QEMU -->|"stdout"| HostStdout

    CRT0 -->|"jump to main"| Hello

    %% Build and debug scripts to environment
    BuildScript --> NixEnv
    RunScript --> QEMU
    DebugScript --> QEMU
    BochsCfg --> QEMU

    %% Click Events
    click LimineDir "https://github.com/iyush/cos/tree/master/limine/"
    click LimineCFG "https://github.com/iyush/cos/blob/master/limine.cfg"
    click Init "https://github.com/iyush/cos/blob/master/kernel/src/entry.c"
    click Init "https://github.com/iyush/cos/blob/master/kernel/src/gdt.c"
    click Init "https://github.com/iyush/cos/blob/master/kernel/src/idt.c"
    click Init "https://github.com/iyush/cos/blob/master/kernel/src/idt.asm"
    click Init "https://github.com/iyush/cos/blob/master/kernel/src/pic.c"
    click Init "https://github.com/iyush/cos/blob/master/kernel/src/pic.h"
    click PMM "https://github.com/iyush/cos/blob/master/kernel/src/pmm.c"
    click ELFLoader "https://github.com/iyush/cos/blob/master/kernel/src/elf.c"
    click ELFLoader "https://github.com/iyush/cos/blob/master/kernel/src/elf.h"
    click Interrupts "https://github.com/iyush/cos/blob/master/kernel/src/idt.c"
    click Interrupts "https://github.com/iyush/cos/blob/master/kernel/src/idt.asm"
    click Interrupts "https://github.com/iyush/cos/blob/master/kernel/src/pic.c"
    click Interrupts "https://github.com/iyush/cos/blob/master/kernel/src/pic.h"
    click Syscall "https://github.com/iyush/cos/blob/master/kernel/src/syscall.asm"
    click Syscall "https://github.com/iyush/cos/blob/master/kernel/src/syscall.c"
    click Scheduler "https://github.com/iyush/cos/blob/master/kernel/src/scheduler.c"
    click Scheduler "https://github.com/iyush/cos/blob/master/kernel/src/scheduler.h"
    click Scheduler "https://github.com/iyush/cos/blob/master/kernel/src/task.c"
    click IO "https://github.com/iyush/cos/blob/master/kernel/src/io.c"
    click IO "https://github.com/iyush/cos/blob/master/kernel/src/kio.c"
    click IO "https://github.com/iyush/cos/blob/master/kernel/src/kio.h"
    click VMM "https://github.com/iyush/cos/blob/master/kernel/src/vmm.c"
    click Utils "https://github.com/iyush/cos/blob/master/kernel/src/defs.c"
    click Utils "https://github.com/iyush/cos/blob/master/kernel/src/assert.h"
    click Utils "https://github.com/iyush/cos/blob/master/kernel/src/cpu.h"
    click Utils "https://github.com/iyush/cos/blob/master/kernel/src/kstring.c"
    click Utils "https://github.com/iyush/cos/blob/master/kernel/src/kstring.h"
    click Utils "https://github.com/iyush/cos/blob/master/kernel/src/stdint.h"
    click Tests "https://github.com/iyush/cos/blob/master/kernel/src/test/test_kstring.c"
    click CRT0 "https://github.com/iyush/cos/blob/master/userland/crt0.asm"
    click Hello "https://github.com/iyush/cos/blob/master/userland/hello-world/main.c"
    click BuildScript "https://github.com/iyush/cos/blob/master/build.sh"
    click RunScript "https://github.com/iyush/cos/blob/master/run.sh"
    click DebugScript "https://github.com/iyush/cos/blob/master/debug.sh"
    click BochsCfg "https://github.com/iyush/cos/blob/master/.bochsrc"
    click NixEnv "https://github.com/iyush/cos/blob/master/shell.nix"

    %% Styles
    classDef hardware fill:#cccccc,stroke:#888888
    classDef bootloader fill:#add8e6,stroke:#4682b4
    classDef kernel fill:#90ee90,stroke:#2e8b57
    classDef userland fill:#ffa500,stroke:#cc8400
    classDef host fill:#cccccc,stroke:#888888
```
