# mncc8337/kerosene architecture

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

- Interactive diagram: https://gitdiagram.com/mncc8337/kerosene
- Repository: https://github.com/mncc8337/kerosene

## Overview

##### Project type and purpose
- This is a hobby-grade, monolithic x86 operating system (Kerosene). It includes a two-stage bootloader (integrated under GRUB for multiboot), a kernel with drivers, memory manager, filesystem support, userland ELF loader, plus a small C standard library and user applications.
- The README confirms it’s an OS: features list (keyboard, framebuffer, FAT32/ramfs, multitasking, syscalls), build instructions, and on-hardware warnings.

##### File structure
- Top level:
- kernel/ (monolithic kernel sources: include/ headers, src/ subdirectories for drivers, mem manager, filesystem, process, syscalls, system)
- libc/ (simple C standard library: stdio, stdlib, string, time)
- userapp/ (simple userland programs, e.g. hi.c)
- fsfiles/ (static files that get embedded into the disk image)
- script/ & Makefile (build and run scripts, ISO and disk-image generation tools)
- linker.ld (linker script for kernel)
- Patterns: a classic OS architecture with clear separation of boot loader, kernel subsystems (drivers, memory, filesystem, process), C library, and userland.

##### README for additional insights
- Confirms use of GRUB multiboot, cross-compiler, nasm, QEMU.
- Notes that fsfiles/ contents get copied into the disk image at build time.
- Scripts orchestrate mounting, ISO generation, running under QEMU.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Boot and Entry
    BIOS["BIOS/GRUB"]:::hw
    Bootloader["Bootloader\n(boot/)"]:::boot
    KernelEntry["Kernel Entry\n(kernel/src/kernel_entry.asm)"]:::kernel
    KernelMain["Kernel Main\n(kernel/src/kernel.c)"]:::kernel
    LinkerScript["Linker Script\n(linker.ld)"]:::kernel

    %% Kernel Subsystems
    subgraph "Kernel Core" 
        direction TB
        %% CPU Mode & Interrupts
        subgraph "CPU & Interrupts"
            direction TB
            GDT["GDT & TSS\n(gdt.asm, gdt.c)"]:::kernel
            IDT["IDT & ISR\n(idt.c, isr.asm, isr.c)"]:::kernel
            IO["I/O Primitives\n(io.c)"]:::kernel
            Panic["Kernel Panic\n(kpanic.c)"]:::kernel
            Spinlock["Spinlock\n(spinlock.c)"]:::kernel
        end
        %% Memory Manager
        subgraph "Memory Manager"
            direction TB
            PM["Physical Allocator\n(pmmngr.c)"]:::kernel
            VM["Virtual Allocator\n(vmmngr.c)"]:::kernel
            KHeap["Kernel Heap\n(kheap.c)"]:::kernel
            Heap["General Heap\n(heap.c)"]:::kernel
        end
        %% Drivers
        subgraph "Drivers"
            direction TB
            PIC["PIC Driver\n(pic.c)"]:::kernel
            PIT["PIT Driver\n(pit.c)"]:::kernel
            ATA["ATA PIO\n(ata_pio.c)"]:::kernel
            PS2["PS/2 Keyboard\n(ps2.c)"]:::kernel
            KBD["Keyboard Layer\n(kbd.c)"]:::kernel
            RTC["RTC Driver\n(rtc.c)"]:::kernel
            Timer["Timer Driver\n(timer.c)"]:::kernel
            Video["Framebuffer/VGA\n(framebuffer.c)"]:::kernel
        end
        %% Filesystem
        subgraph "Filesystem"
            direction TB
            VFS["VFS & Ops\n(vfs.c, vfs_op.c)"]:::kernel
            FAT32["FAT32\n(fat32.c, mbr.c)"]:::kernel
            RAMFS["ramfs\n(ramfs.c)"]:::kernel
            FileOp["File Ops\n(file_op.c, fs_op.c)"]:::kernel
        end
        %% Process & Scheduling
        subgraph "Process & Scheduling"
            direction TB
            ProcessMgr["Process Manager\n(process.c)"]:::kernel
            Scheduler["Scheduler\n(scheduler.c)"]:::kernel
        end
        %% Syscall Interface
        Syscall["Syscall Interface\n(syscall.c)"]:::kernel
        %% ELF Loader & Misc
        subgraph "ELF & Misc"
            direction TB
            ELFLoader["ELF Loader\n(elf.c)"]:::kernel
            PSFLoader["PSF Loader\n(psf.c)"]:::kernel
        end
    end

    %% Userland and Libc
    subgraph "Userland"
        direction TB
        LibC["C Standard Library\n(libc/)"]:::user
        UserApp["User Application\n(hi.c)"]:::user
    end

    %% Disk Image & Build Tools
    fsfiles["Disk Image Files\n(fsfiles/)"]:::disk
    subgraph "Build Tools"
        direction TB
        Makefile["Makefile & Config"]:::build
        BuildScripts["Scripts\n(script/)"]:::build
    end

    %% Hardware
    Hardware["Hardware Devices"]:::hw

    %% Connections
    BIOS -->|"multiboot load"| Bootloader
    Bootloader -->|"load kernel"| KernelEntry
    KernelEntry -->|"init"| KernelMain
    KernelMain -->|"link script"| LinkerScript
    KernelMain -->|"setup CPU"| GDT
    KernelMain -->|"setup IDT"| IDT
    KernelMain -->|"init IO"| IO
    KernelMain -->|"panic/spin"| Panic
    KernelMain -->|"alloc mem"| PM
    PM --> VM
    VM --> KHeap
    KHeap --> Heap
    KernelMain --> PIC
    KernelMain --> PIT
    KernelMain --> ATA
    KernelMain --> PS2
    KernelMain --> KBD
    KernelMain --> RTC
    KernelMain --> Timer
    KernelMain --> Video
    Video --> Hardware
    KernelMain --> VFS
    VFS --> FAT32
    VFS --> RAMFS
    VFS --> FileOp
    FAT32 --> fsfiles
    KernelMain --> ProcessMgr
    ProcessMgr --> Scheduler
    KernelMain --> Syscall
    KernelMain --> ELFLoader
    ELFLoader --> PSFLoader
    UserApp -->|"syscall"| Syscall
    UserApp -->|"link "| LibC
    BuildScripts -->|"embed"| fsfiles
    Makefile -->|"build image"| BuildScripts
    fsfiles -->|"mounted"| VFS

    %% Click Events
    click Bootloader "https://github.com/mncc8337/kerosene/tree/master/boot/"
    click KernelEntry "https://github.com/mncc8337/kerosene/blob/master/kernel/src/kernel_entry.asm"
    click KernelMain "https://github.com/mncc8337/kerosene/blob/master/kernel/src/kernel.c"
    click LinkerScript "https://github.com/mncc8337/kerosene/blob/master/linker.ld"
    click GDT "https://github.com/mncc8337/kerosene/blob/master/kernel/src/system/gdt.asm"
    click IDT "https://github.com/mncc8337/kerosene/blob/master/kernel/src/system/idt.c"
    click IO "https://github.com/mncc8337/kerosene/blob/master/kernel/src/system/io.c"
    click Panic "https://github.com/mncc8337/kerosene/blob/master/kernel/src/system/kpanic.c"
    click Spinlock "https://github.com/mncc8337/kerosene/blob/master/kernel/src/system/spinlock.c"
    click PM "https://github.com/mncc8337/kerosene/blob/master/kernel/src/mem/pmmngr.c"
    click VM "https://github.com/mncc8337/kerosene/blob/master/kernel/src/mem/vmmngr.c"
    click KHeap "https://github.com/mncc8337/kerosene/blob/master/kernel/src/mem/kheap.c"
    click Heap "https://github.com/mncc8337/kerosene/blob/master/kernel/src/mem/heap.c"
    click PIC "https://github.com/mncc8337/kerosene/blob/master/kernel/src/driver/pic.c"
    click PIT "https://github.com/mncc8337/kerosene/blob/master/kernel/src/driver/pit.c"
    click ATA "https://github.com/mncc8337/kerosene/blob/master/kernel/src/driver/ata/ata_pio.c"
    click PS2 "https://github.com/mncc8337/kerosene/blob/master/kernel/src/driver/ps2.c"
    click KBD "https://github.com/mncc8337/kerosene/blob/master/kernel/src/driver/kbd.c"
    click RTC "https://github.com/mncc8337/kerosene/blob/master/kernel/src/driver/rtc.c"
    click Timer "https://github.com/mncc8337/kerosene/blob/master/kernel/src/driver/timer.c"
    click Video "https://github.com/mncc8337/kerosene/blob/master/kernel/src/driver/video/framebuffer.c"
    click VFS "https://github.com/mncc8337/kerosene/blob/master/kernel/src/filesystem/vfs.c"
    click FAT32 "https://github.com/mncc8337/kerosene/blob/master/kernel/src/filesystem/fat32.c"
    click RAMFS "https://github.com/mncc8337/kerosene/blob/master/kernel/src/filesystem/ramfs.c"
    click FileOp "https://github.com/mncc8337/kerosene/blob/master/kernel/src/filesystem/file_op.c"
    click ProcessMgr "https://github.com/mncc8337/kerosene/blob/master/kernel/src/process/process.c"
    click Scheduler "https://github.com/mncc8337/kerosene/blob/master/kernel/src/process/scheduler.c"
    click Syscall "https://github.com/mncc8337/kerosene/blob/master/kernel/src/syscall.c"
    click ELFLoader "https://github.com/mncc8337/kerosene/blob/master/kernel/src/misc/elf.c"
    click PSFLoader "https://github.com/mncc8337/kerosene/blob/master/kernel/src/misc/psf.c"
    click LibC "https://github.com/mncc8337/kerosene/tree/master/libc/"
    click UserApp "https://github.com/mncc8337/kerosene/blob/master/userapp/hi.c"
    click fsfiles "https://github.com/mncc8337/kerosene/tree/master/fsfiles/"
    click BuildScripts "https://github.com/mncc8337/kerosene/tree/master/script/"
    click Makefile "https://github.com/mncc8337/kerosene/tree/master/Makefile"

    %% Styles
    classDef boot fill:#cccccc,stroke:#333,stroke-width:1px
    classDef kernel fill:#add8e6,stroke:#333,stroke-width:1px
    classDef user fill:#90ee90,stroke:#333,stroke-width:1px
    classDef build fill:#ffa500,stroke:#333,stroke-width:1px
    classDef disk fill:#ffff99,stroke:#333,stroke-width:1px
    classDef hw fill:#ffff99,stroke:#333,stroke-width:1px
```
