# maastaar/539kernel architecture

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

- Interactive diagram: https://gitdiagram.com/maastaar/539kernel
- Repository: https://github.com/maastaar/539kernel

## Overview

##### Project Type and Purpose
- This is an educational, monolithic x86 32-bit kernel (no user-land or network stack) intended to illustrate OS internals (bootloader, protected-mode setup, memory management, scheduling, drivers, filesystem).

##### File Structure
- Top level:
- `src/` – contains the “final” kernel code and all subsystems as they stand at the book’s end.
- `evolution_by_versions/` – step-by-step kernel versions per chapter.
- Within `src/`:
- Assembly modules for early initialization and switching to protected mode:
– `bootstrap.asm`, `starter.asm`, `simple_kernel.asm`, `gdt.asm`, `idt.asm`
- C modules for core subsystems:
– `main.c` (entrypoint)
– `process.{c,h}`, `scheduler.{c,h}` (process management, round-robin scheduler)
– `heap.{c,h}`, `paging.{c,h}` (memory management, paging, heap allocator)
– `filesystem.{c,h}`, `ata.{c,h}` (block-device driver, file system)
– `screen.{c,h}` (VGA text driver)
– `str.{c,h}` (basic string routines)
- `linker.ld` – the ELF/linker script defining memory layout
- `Makefile` – orchestrates assembling, compiling, linking, and generating the bootable image
- `bochs` – Bochs emulator config for testing

##### README
- Confirms this is purely an educational kernel and that `src/` is the latest codebase.
- No network protocols, GUIs, or user-space—everything runs in one address space under Bochs or real hardware.

a. Boot Path Components
- BIOS/Emulator (Bochs) → Bootloader (`bootstrap.asm`) → Protected-Mode Setup (`gdt.asm`, `idt.asm`) → Kernel Entry (`starter.asm`)
1. Memory Management
- Paging module (paging.c/h)
- Heap allocator (heap.c/h)
2. Process Management
- Process abstraction (process.c/h)
- Scheduler (scheduler.c/h)
3. Device Drivers
- ATA driver (ata.c/h) → used by Filesystem
- Screen/VGA text driver (screen.c/h)
4. Filesystem Module (filesystem.c/h)
5. Utilities
- String library (str.c/h)
6. Kernel Entrypoint (`main.c`)
c. Build & Link Pipeline
- Source (ASM & C) → Assembly/Compilation → Linker script (`linker.ld`) → Kernel binary → Bootable image via `Makefile`
d. Testing Environment
- Bochs emulator config used to run the image

##### Relationships & Data Flows
- Kernel Entry → Memory Manager init
- Memory Manager ↔ Paging & Heap modules
- Kernel Entry → Interrupt subsystem (IDT)
- Kernel Entry → Process Manager → Scheduler
- Scheduler → Process switching
- Device Drivers → provide primitives to Filesystem and Process (e.g., load code)
- Main loop in `main.c` tying everything together (init then dispatch)
- Build pipeline at the bottom: Tools → AS/CC → Linker → Image → Bochs

##### Architectural Patterns & Principles
- Monolithic kernel: all code linked into one binary
- Separation of concerns: distinct modules for CPU init, memory, processes, drivers, FS
- Linear bootstrap chain: real mode → protected mode → kernel C runtime
- Educational layering: each chapter adds one module (captured in `evolution_by_versions/`)

- Clear labels for each component and module
- A note calling out this is a monolithic, single-address-space, educational kernel

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Boot & CPU Init
    subgraph "Boot & CPU Init"
        direction TB
        BIOS["BIOS / Bochs (Emulator)"]:::external
        Bootloader["bootstrap.asm"]:::boot
        GDT["gdt.asm"]:::boot
        IDT["idt.asm"]:::boot
        Starter["starter.asm"]:::boot
    end

    BIOS -->|"boot"| Bootloader
    Bootloader -->|"loads GDT"| GDT
    GDT -->|"initializes IDT"| IDT
    IDT -->|"jumps to C runtime"| Starter

    click Bootloader "https://github.com/maastaar/539kernel/blob/master/src/bootstrap.asm"
    click GDT "https://github.com/maastaar/539kernel/blob/master/src/gdt.asm"
    click IDT "https://github.com/maastaar/539kernel/blob/master/src/idt.asm"
    click Starter "https://github.com/maastaar/539kernel/blob/master/src/starter.asm"

    %% Kernel Core
    subgraph "Kernel (monolithic 32-bit x86)" 
        direction TB
        Main["main.c"]:::entry

        subgraph "Memory Management" 
            direction TB
            Paging["paging.c/h"]:::memory
            Heap["heap.c/h"]:::memory
        end

        subgraph "Process Management"
            direction TB
            Process["process.c/h"]:::process
            Scheduler["scheduler.c/h"]:::process
        end

        subgraph "Device Drivers & Filesystem"
            direction TB
            ATA["ata.c/h"]:::driver
            Screen["screen.c/h"]:::driver
            Filesystem["filesystem.c/h"]:::driver
        end

        subgraph "Utilities"
            direction TB
            Str["str.c/h"]:::util
        end

        Main -->|"init memory"| Paging
        Paging <-->|"allocates pages"| Heap
        Main -->|"init interrupt subsystem"| IDT
        Main -->|"init processes"| Process
        Process -->|"init scheduler"| Scheduler
        Scheduler -->|"process switching"| Process
        ATA -->|"raw disk I/O"| Filesystem
        Screen -->|"console output"| Main
        Filesystem -->|"file operations"| Main
        Main --> Str
    end

    click Main "https://github.com/maastaar/539kernel/blob/master/src/main.c"
    click Paging "https://github.com/maastaar/539kernel/blob/master/src/paging.c"
    click Heap "https://github.com/maastaar/539kernel/blob/master/src/heap.c"
    click Process "https://github.com/maastaar/539kernel/blob/master/src/process.c"
    click Scheduler "https://github.com/maastaar/539kernel/blob/master/src/scheduler.c"
    click ATA "https://github.com/maastaar/539kernel/blob/master/src/ata.c"
    click Screen "https://github.com/maastaar/539kernel/blob/master/src/screen.c"
    click Filesystem "https://github.com/maastaar/539kernel/blob/master/src/filesystem.c"
    click Str "https://github.com/maastaar/539kernel/blob/master/src/str.c"

    %% Build & Link Pipeline
    subgraph "Build & Link Pipeline"
        direction TB
        Source["ASM & C source"]:::build
        Compile["Assembler/Compiler"]:::build
        Link["linker.ld"]:::build
        Binary["Kernel binary"]:::build
        Image["Bootable image"]:::build
        Source -->|"assemble/compile"| Compile
        Compile -->|"link with script"| Link
        Link -->|"produce binary"| Binary
        Binary -->|"mkfs & embed"| Image
        Image -->|"run"| BIOS
    end

    click Link "https://github.com/maastaar/539kernel/blob/master/src/linker.ld"
    click Source "https://github.com/maastaar/539kernel/tree/master/src/Makefile"
    click Image "https://github.com/maastaar/539kernel/tree/master/src/bochs"

    %% Legend
    subgraph Legend
        direction TB
        A["Blue = Boot & CPU init"]:::boot
        B["Green = Memory subsystems"]:::memory
        C["Orange = Process subsystems"]:::process
        D["Purple = Drivers & FS"]:::driver
        E["Gray = Utilities & scripts"]:::util
        F["Yellow = Build tools"]:::build
        G["External = Emulator/Host"]:::external
    end

    classDef boot fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef memory fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef process fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef driver fill:#e1bee7,stroke:#6a1b9a,color:#6a1b9a;
    classDef util fill:#eeeeee,stroke:#424242,color:#424242;
    classDef build fill:#fff9c4,stroke:#f57f17,color:#f57f17;
    classDef external fill:#f5f5f5,stroke:#9e9e9e,color:#424242;
    classDef entry fill:#ffcdd2,stroke:#b71c1c,color:#b71c1c;
```
