# gooberheads6297/gooberosx86 architecture

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

- Interactive diagram: https://gitdiagram.com/gooberheads6297/gooberosx86
- Repository: https://github.com/gooberheads6297/gooberosx86

## Overview

##### Project Type and Purpose
- This is a hobby‐grade x86 operating system (“GooberOSx86”) consisting of:
- A bootloader stage (GRUB configuration + minimal assembly stubs)
- A monolithic kernel written in C/assembly
- Built-in drivers (keyboard, timer, VGA video)
- A simple filesystem layer
- An interactive shell

##### File Structure Analysis
Top-Level
├── boot.s, gdt.s, idt_load.s, isr32_stub.s, irq0/1_wrapper.s
├── kernel.c / kernel.h
├── shell/ (shell.c, shell.h)
├── drivers/ (io, keyboard, timer, video)
├── fs/ (filesystem.c, filesystem.h)
├── grub/ & iso/boot/grub (grub.cfg)
├── linker.ld, build scripts, build output

Key Patterns
- Assembly modules handle early CPU setup: GDT, IDT, ISRs, IRQs
- C modules grouped by functionality: core kernel, drivers, filesystem, shell
- GRUB is used as the bootloader front-end
- A single binary (kernel.bin) loaded by GRUB

##### README Insights
- Monolithic design, with a kernel binary directly containing drivers and shell
- No mention of user-space vs kernel-space separation beyond shell
- Targeting legacy BIOS/MBR boot

##### Components
a. External/Hardware
- PC BIOS / Firmware
- Physical hardware buses: VGA, Keyboard, PIT (timer), Disk

b. Bootloader Stage
- GRUB (grub.cfg)
- Assembly stubs (boot.s → load kernel.bin)

c. Kernel Initialization
- Assembly Modules: gdt.s, idt_load.s, isr32_stub.s, irq_wrapper.s
- C entrypoint in kernel.c

d. Kernel Core Subsystems
- Descriptor & Interrupt Management
- Memory layout (via linker.ld)

e. Drivers Layer
- IO helpers
- Keyboard driver
- VGA (video) driver
- Timer driver

f. Filesystem Subsystem (fs/filesystem.c)

g. Shell Application (shell/shell.c)

##### Relationships & Data Flows
- BIOS → GRUB → loads kernel.bin into memory
- Bootloader → invokes kernel’s entrypoint
- Kernel init sequence:
1. Setup GDT/IDT
2. Register ISRs / IRQ handlers
3. Initialize drivers
4. Mount/init filesystem
5. Spawn shell
- Shell ↔ Filesystem for I/O
- Kernel ↔ Drivers ↔ Hardware for device interactions
- Interrupts flow hardware→IRQ handler→kernel ISR

##### Architectural Patterns & Design Principles
- Monolithic kernel (all components linked into one binary)
- Layered initialization: bootloader → CPU setup → drivers → higher-level services → shell
- Clear separation of concerns by directory (assembly vs C, drivers vs core vs apps)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Firmware & Bootloader Layer
    subgraph "Firmware & Bootloader"
        BIOS["PC BIOS / Firmware"]:::ext
        GRUB["GRUB Configuration"]:::ext
        ISO_GRUB["ISO GRUB Configuration"]:::ext
        boot_s["boot.s"]:::assembly
        gdt_stub["gdt.s"]:::assembly
        idt_stub["idt_load.s"]:::assembly
        isr32_stub["isr32_stub.s"]:::assembly
        irq0_stub["irq0_wrapper.s"]:::assembly
        irq1_stub["irq1_wrapper.s"]:::assembly
    end

    %% Kernel Binary Layer
    subgraph "Kernel Binary"
        subgraph "Kernel Core" 
            Kentry["kernel.c / kernel.h"]:::kernel
            Linker["linker.ld"]:::kernel
            subgraph "Descriptor & Interrupt Management"
                gdt_stub_core["gdt.s"]:::assembly
                idt_stub_core["idt_load.s"]:::assembly
                isr32_stub_core["isr32_stub.s"]:::assembly
                irq0_stub_core["irq0_wrapper.s"]:::assembly
                irq1_stub_core["irq1_wrapper.s"]:::assembly
            end
        end

        subgraph "Drivers"
            IO["IO Helper Layer"]:::drivers
            Keyboard["Keyboard Driver"]:::drivers
            Timer["Timer Driver"]:::drivers
            Video["VGA (Video) Driver"]:::drivers
        end

        FS["Filesystem Subsystem"]:::fs
        Shell["Interactive Shell"]:::shell
    end

    %% Hardware Layer
    subgraph "Hardware"
        VGA_BUS["VGA Bus"]:::ext
        KEYBUS["Keyboard Bus"]:::ext
        PIT["PIT (Timer)"]:::ext
        DISK["Disk"]:::ext
    end

    %% Control / Data Flow
    BIOS -->|"loads GRUB"| GRUB
    GRUB -->|"reads grub.cfg"| ISO_GRUB
    ISO_GRUB -->|"loads assembly stubs"| boot_s
    boot_s -->|"jump to kernel entry"| Kentry
    Kentry -->|"initializes GDT/IDT"| gdt_stub_core
    Kentry -->|"initializes GDT/IDT"| idt_stub_core
    Kentry -->|"registers ISRs/IRQs"| isr32_stub_core
    Kentry -->|"registers ISRs/IRQs"| irq0_stub_core
    Kentry -->|"registers ISRs/IRQs"| irq1_stub_core
    Kentry -->|"calls driver_init()"| IO
    IO -->|"provides I/O helpers"| Keyboard
    IO -->|"provides I/O helpers"| Timer
    IO -->|"provides I/O helpers"| Video
    IO -->|"provides I/O helpers"| FS
    FS -->|"mount/init filesystem"| Kentry
    Kentry -->|"spawns shell"| Shell
    Shell -->|"fs I/O"| FS

    %% Device Interaction
    KEYBUS -->|IRQ1| irq1_stub_core
    PIT -->|IRQ0| irq0_stub_core
    irq1_stub_core -->|"keyboard ISR"| Keyboard
    irq0_stub_core -->|"timer ISR"| Timer
    VGA_BUS -->|"vga_write()"| Video
    Disk -->|"read_sector()"| FS

    %% Click Events
    click GRUB "https://github.com/gooberheads6297/gooberosx86/blob/main/grub/grub.cfg"
    click ISO_GRUB "https://github.com/gooberheads6297/gooberosx86/blob/main/iso/boot/grub/grub.cfg"
    click boot_s "https://github.com/gooberheads6297/gooberosx86/blob/main/boot.s"
    click gdt_stub "https://github.com/gooberheads6297/gooberosx86/blob/main/gdt.s"
    click idt_stub "https://github.com/gooberheads6297/gooberosx86/blob/main/idt_load.s"
    click isr32_stub "https://github.com/gooberheads6297/gooberosx86/blob/main/isr32_stub.s"
    click irq0_stub "https://github.com/gooberheads6297/gooberosx86/blob/main/irq0_wrapper.s"
    click irq1_stub "https://github.com/gooberheads6297/gooberosx86/blob/main/irq1_wrapper.s"
    click Kentry "https://github.com/gooberheads6297/gooberosx86/blob/main/kernel.c"
    click Linker "https://github.com/gooberheads6297/gooberosx86/blob/main/linker.ld"
    click IO "https://github.com/gooberheads6297/gooberosx86/blob/main/drivers/io/io.h"
    click Keyboard "https://github.com/gooberheads6297/gooberosx86/blob/main/drivers/keyboard/keyboard.c"
    click Timer "https://github.com/gooberheads6297/gooberosx86/blob/main/drivers/timer/timer.c"
    click Video "https://github.com/gooberheads6297/gooberosx86/blob/main/drivers/video/vga.c"
    click FS "https://github.com/gooberheads6297/gooberosx86/blob/main/fs/filesystem.c"
    click Shell "https://github.com/gooberheads6297/gooberosx86/blob/main/shell/shell.c"

    %% Styles
    classDef assembly fill:#DDDDDD,stroke:#999
    classDef kernel fill:#ADD8E6,stroke:#0066CC
    classDef drivers fill:#FFA500,stroke:#CC8400
    classDef fs fill:#90EE90,stroke:#339933
    classDef shell fill:#DDA0DD,stroke:#993399
    classDef ext fill:#F0F0F0,stroke:#666666,stroke-dasharray: 2 2
```
