# stpoen/hedgehogos architecture

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

- Interactive diagram: https://gitdiagram.com/stpoen/hedgehogos
- Repository: https://github.com/stpoen/hedgehogos

## Overview

##### Project Type and Purpose
- HedgehogOS is a teaching‐oriented, 64-bit open-source operating system written in C and x86-64 Assembly (NASM). It implements a Multiboot2‐compatible boot sequence, basic paging support (PAE), interrupt handling, a minimal CLI shell via VGA text mode, and parts of a custom libc.

##### Main Components
a. Host/Build Environment
- Cross-Compiler Toolchain (GCC, binutils)
- Makefiles and Build Scripts (root Makefile, kernel/Makefile, libc/Makefile, make.config)
- Output Artifacts: object files (*.o), kernel binary (k.bin), ISO image (hgh.iso)
b. Boot & Loader Layer
- BIOS or QEMU (emulated hardware)
- GRUB Multiboot2 Stage (grub.cfg + grub modules)
c. Kernel Entry & Initialization
- Assembly Boot Code (kernel/arch/x86/boot.asm, init_long_mode.asm)
- Linker Script (kernel/arch/x86/linker.ld)
- C Entry Point (kernel/boot/kmain.c)
d. Core Kernel Subsystems
- CPU & Interrupt Setup: IDT (kernel/interrupts/idt.c/h), ISR (isr.c), interrupt.asm
- Memory Management: Frame Allocator (kernel/memory/frame_alloc.c/h), PAE paging prep
- Syscalls / I/O Primitives: inb/outb/io_wait (kernel/sys/io/*.c)
e. Device Drivers & Services
- VGA Text Driver (kernel/drivers/tty/vga.c/h)
- PS/2 Keyboard Driver (kernel/drivers/keyboard/ps2/*.h)
- Terminal Services (kernel/services/tty.c)
f. User Interface Layer
- Simple CLI Shell (invoked in kmain via print/scan routines using VGA & keyboard)
- libc Stubs (libc/{stdlib,stdio,string,math} implementations used by kernel shell)

##### Relationships and Data Flows
- Build Flow: Source → (Makefiles) → Cross-Compiler → Object Files → Kernel Binary & ISO → Boot Medium
- Boot Flow: BIOS/QEMU → GRUB → Loads k.bin → jump to Assembly init → switch to 64-bit → call kmain
- At Runtime:
- Hardware Interrupt → ISR → Keyboard Driver → Terminal Service → Shell Input Logic
- Shell Output → printf (libc) → VGA Driver → Video Memory → Display
- Memory Requests → Frame Allocator → Page Tables (PAE)

##### Architectural Patterns & Design Principles
- Layered Architecture: separation between boot stage (assembly), kernel core (C), drivers, and shell.
- Monolithic Kernel: all subsystems (interrupts, memory, drivers, CLI) compiled into one binary.
- Minimal libc integration: deep in‐kernel use of standard library routines for string, math, I/O.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build Host Layer
    subgraph "Build Host Layer"
        direction TB
        RootScripts["Root Build Scripts\n(Makefile, make.config)"]:::build
        CrossCompiler["Cross-Compiler Toolchain\n(GCC, binutils)"]:::external
        KernelBuild["Kernel Build Script\n(kernel/Makefile)"]:::build
        LibcBuild["Libc Build Script\n(libc/Makefile)"]:::build
        subgraph "Output Artifacts"
            direction TB
            ObjFiles[(Object Files\n*.o)]:::artifact
            KBin[(Kernel Binary\nk.bin)]:::artifact
            ISO[(ISO Image\nhgh.iso)]:::artifact
        end
    end

    RootScripts -->|uses| CrossCompiler
    RootScripts -->|includes| KernelBuild
    RootScripts -->|includes| LibcBuild
    KernelBuild -->|compiles| ObjFiles
    CrossCompiler -->|generates| ObjFiles
    ObjFiles -->|links| KBin
    KBin -->|packs| ISO

    %% Boot Loader Layer
    subgraph "Boot Loader Layer"
        direction TB
        BIOS["BIOS / QEMU"]:::external
        GRUB["GRUB Multiboot2 Stage\n(grub.cfg, modules)"]:::external
    end

    ISO -->|boot medium| BIOS
    BIOS -->|loads| GRUB
    GRUB -->|load k.bin| KBin

    %% Kernel Init Layer
    subgraph "Kernel Init Layer"
        direction TB
        BootASM["boot.asm\n(Real→Prot Mode)"]:::assembly
        LongModeASM["init_long_mode.asm\n(Long-mode switch)"]:::assembly
        IntStubASM["interrupts.asm\n(ASM stubs)"]:::assembly
        Linker["linker.ld"]:::config
        KMain["kmain.c\n(C entry point)"]:::c
    end

    GRUB -->|jump| BootASM
    BootASM -->|switch| LongModeASM
    LongModeASM -->|call| KMain
    ObjFiles -->|linked by| Linker
    Linker -->|produces| KBin

    %% Kernel Subsystems Layer
    subgraph "Kernel Subsystems Layer"
        direction TB
        subgraph "Interrupt Handling"
            direction TB
            IDT["idt.c / idt.h"]:::c
            ISR["isr.c"]:::c
        end
        subgraph "Memory Management"
            direction TB
            FrameAlloc["frame_alloc.c / frame_alloc.h"]:::c
        end
        subgraph "I/O Primitives"
            direction TB
            Inb["inb.c"]:::c
            Outb["outb.c"]:::c
            IOWait["io_wait.c"]:::c
            IOHdr["io.h"]:::config
        end
        subgraph "Device Drivers"
            direction TB
            VGA["vga.c / vga.h"]:::c
            PS2["scan_codes_set1.h"]:::config
        end
        subgraph "Terminal Services"
            direction TB
            TTYServ["tty.c"]:::c
            TTYHdr["tty.h"]:::config
        end
    end

    KMain -->|"init IDT"| IDT
    KMain -->|"setup ISR"| ISR
    KMain -->|"prepare paging"| FrameAlloc
    KMain -->|"init I/O"| Inb
    KMain -->|"init I/O"| Outb
    KMain -->|"init I/O"| IOWait
    KMain -->|"start drivers"| VGA
    KMain -->|"start drivers"| PS2
    IDT -->|"on interrupt"| ISR
    ISR -.->|hardware interrupt| PS2
    PS2 -->|key event| TTYServ
    TTYServ -->|provide API| TTYHdr

    %% Shell / UI Layer
    subgraph "Shell / UI Layer"
        direction TB
        Shell["CLI Shell"]:::c
        subgraph "libc Stubs"
            direction TB
            Stdlib["stdlib: atoi, dtoa, itoa"]:::c
            Stdio["stdio: printf"]:::c
            StringLib["string: memset, strlen, strncpy"]:::c
            MathLib["math: modf, pow"]:::c
            LibcHdrs["libc headers"]:::config
        end
    end

    TTYServ -->|input/output| Shell
    Shell -->|calls| Stdlib
    Shell -->|calls| Stdio
    Shell -->|calls| StringLib
    Shell -->|calls| MathLib
    Shell -->|uses| LibcHdrs
    Shell -->|output| VGA

    %% Styles
    classDef build fill:#b3e6b3,stroke:#339933,color:#000;
    classDef external fill:#e6e6e6,stroke:#999999,color:#333;
    classDef assembly fill:#f4cccc,stroke:#cc0000,color:#000;
    classDef c fill:#c9daf8,stroke:#1155cc,color:#000;
    classDef config fill:#ffe599,stroke:#cc7a00,color:#000;
    classDef artifact fill:#dddddd,stroke:#666666,shape:cylinder,color:#000;

    %% Click Events
    click RootScripts "https://github.com/stpoen/hedgehogos/tree/main/Makefile"
    click KernelBuild "https://github.com/stpoen/hedgehogos/tree/main/kernel/Makefile"
    click LibcBuild "https://github.com/stpoen/hedgehogos/tree/main/libc/Makefile"
    click ObjFiles "https://github.com/stpoen/hedgehogos/blob/main/build_x86_64/*.o"
    click KBin "https://github.com/stpoen/hedgehogos/blob/main/build_x86_64/iso/k.bin"
    click ISO "https://github.com/stpoen/hedgehogos/blob/main/build_x86_64/hgh.iso"
    click GRUB "https://github.com/stpoen/hedgehogos/blob/main/build_x86_64/iso/boot/grub/grub.cfg"
    click BootASM "https://github.com/stpoen/hedgehogos/blob/main/kernel/arch/x86/boot.asm"
    click LongModeASM "https://github.com/stpoen/hedgehogos/blob/main/kernel/arch/x86/init_long_mode.asm"
    click IntStubASM "https://github.com/stpoen/hedgehogos/blob/main/kernel/arch/x86/interrupts.asm"
    click Linker "https://github.com/stpoen/hedgehogos/blob/main/kernel/arch/x86/linker.ld"
    click KMain "https://github.com/stpoen/hedgehogos/blob/main/kernel/boot/kmain.c"
    click IDT "https://github.com/stpoen/hedgehogos/blob/main/kernel/interrupts/idt.c"
    click ISR "https://github.com/stpoen/hedgehogos/blob/main/kernel/interrupts/isr.c"
    click FrameAlloc "https://github.com/stpoen/hedgehogos/blob/main/kernel/memory/frame_alloc.c"
    click Inb "https://github.com/stpoen/hedgehogos/blob/main/kernel/sys/io/inb.c"
    click Outb "https://github.com/stpoen/hedgehogos/blob/main/kernel/sys/io/outb.c"
    click IOWait "https://github.com/stpoen/hedgehogos/blob/main/kernel/sys/io/io_wait.c"
    click IOHdr "https://github.com/stpoen/hedgehogos/blob/main/kernel/sys/include/io.h"
    click VGA "https://github.com/stpoen/hedgehogos/blob/main/kernel/drivers/tty/vga.c"
    click PS2 "https://github.com/stpoen/hedgehogos/blob/main/kernel/drivers/keyboard/ps2/scan_codes_set1.h"
    click TTYServ "https://github.com/stpoen/hedgehogos/blob/main/kernel/services/tty.c"
    click TTYHdr "https://github.com/stpoen/hedgehogos/blob/main/kernel/include/tty.h"
    click Stdlib "https://github.com/stpoen/hedgehogos/blob/main/libc/stdlib/atoi.c"
    click Stdio "https://github.com/stpoen/hedgehogos/blob/main/libc/stdio/printf.c"
    click StringLib "https://github.com/stpoen/hedgehogos/blob/main/libc/string/memset.c"
    click MathLib "https://github.com/stpoen/hedgehogos/blob/main/libc/math/modf.c"
    click LibcHdrs "https://github.com/stpoen/hedgehogos/blob/main/libc/include/stdlib.h"
```
